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URULE NOH 


Nobody ever said programming 
PCs was supposed to be easy. 

But does it have to be tedious 
and time-consuming, too? 

Not any more. 

Not since the arrival of the 
remarkable new program in the 
lower right-hand corner. 

Which is designed to save you 
most of the time you're currently 
spending searching through the 
books and manuals on the shelf 
above. 

It’s one of a quintet of pop-up 
reference packages, called the 
Norton On-Line Programmer’s 
Guides, that actually gather your 
data for you—on OS/2 Kernel API 
or your favorite programming 
language. 

Each patie comes complete 
with a comprehensive, cross- 
referenced database crammed 
with just about everything you 
need to know to write applications. 


Not to mention a wealth of wisdom from 
the Norton team of top programmers. 
(PC Week used the words “massive” and 


\ 


for people 


“authoritatively detailed” to 
describe the information 


DATA AND FEATURES 


OS/2 KERNEL API (1M of data) C (600K each database) 
# Kernel API: Describes all OS/2 API = Microsoft C and Turbo C: Describes 
services: DOSx,KBDx,MOUxand VIOx. _ the C language. 


= Structure Tables: Lists all of the OS/2 
data structures used in the Kernel API. 
® Conversion Guide: DOS-to-OS/2 table 
shows which OS/2 calls replace DOS 
and ROM BIOS services. 


ASSEMBLY (600K of data) 

} # DOS Service Calls: All INT 21h serv- 

] ices,interrupts, error codes and more. 

= ROM BIOS Calls: All ROM calls. 

= Instruction Set: All 8088/86 instruc- 
tions, addressing modes, flags, bytes per 
instruction, clock cycles and more. 

= MASM: Pseudo-ops and assembler 


@ Library Functions: Detailed descrip- 
tions of all functions. 
= Preprocessor Directives: Describes 
commands, usage and syntax. 

PASCAL—Turbo (360K of data) 
= Language: Describes statements, syn- 
tax, operators, data types and records. 
@ Library: Describes the library proce- 
dures and functions. 

FEATURES (all versions) 

= Memory-resident—uses just 71K. 
® Full-screen or moveable half-screen 
view, with pull-down menus. 


directives. ® Auto lookup and searching. 
® Tools for creating your own databases. 
BASIC (270K each database) = More data: All five Norton Guides fea- 


= IBM BASICA, Microsoft QuickBASIC 
and TurboBASIC. 

= Statements and Functions: Describes 
all statements and built-in library func- 
tions. 


ture a variety of tables, including ASCII 
characters, line-drawing characters, 
keyboard scan codes and much more. 
® Includes both OS/2 protected mode 
and DOS versions. 


contained in the Guides. If you’d rather see for 
yourself, you might take a moment or two to 
examine the data box you just passed.) 

You can, of course, find most of this informa- 


Designed for the IBM” PS/2° and PC families, and 100% compatibles. Available at most software 


tion in the books and manuals on our shelf. 

But Peter Norton—who’s written a few 
books himself— figured you'd rather have it 
on your screen. 

Instantly. 

In either full-screen or moveable half- 
screen mode. 

Popping up right next to your work. Right 


TAT 


A Guides reference summary 
screen (shown in blue) pops up on 
top of the program you're working 

on (shown in green). 


Summary data expands on 
command into extensive detail. 
And you can select from a wide 

variety of information. 


where you need it. 

This, you're probably thinking, is precisely 
the kind of thinking that produced the classic 
Norton Utilities. 

And youre right. 

But even Peter Norton can’t think of 
everything. 

Which is why each version of the Norton 
Guides comes equipped with a built-in com- 


piler—the same compiler used to develop the 
databases contained in the Guides. 

So you can create new databases of your own, 
complete with electronic indexing and cross- 
referencing. 

No wonder PC Week refers to the Guides as a 
“set of programs that will delight programmers’ 
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BEGIN 


ack when I was 15 and 
impatient, I decided to 
build a car. I conned my 
uncle out of his broken 
self-propelled reel-style lawn- 
mower that would only go back- 
wards, scrounged some scrap 

2 X 4s and pipe fittings from a 
Chicago vacant lot, took apart my 
old balloon-tire bike with the 
cracked frame, and I built a car. 
By bolting the wood frame onto 
the wrong side of the lawnmower, 
I worked around the frozen gear- 
box. With the frame slung wnder 
the balloon-tired front axle and a 
sawed-off bar stool as the front 
seat, it was, shall we say, idiosyn- 
cratic. But it ran up and down the 
alley at a reliable seven miles per 
hour until the neighbors com- 
plained. 

Had I been less impatient, I 
could have grown up, bought a 
raft of machine tools, and in 
about 15 years hand-cloned a 
Porsche. In the meantime, how- 
ever, I would still be taking the 
bus. 

Most people don’t build cars, 
and most people don’t write soft- 
ware. Those of us who do, gener- 
ally approach it as though we 
were hand-cloning a Porsche: 
starting at the top with the specifi- 
cation of the gleaming end- 
product, and then painstakingly 
creating a multitude of special- 
purpose components that, bolted 
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Standardized parts. 


Jeff Duntemann 


together with care, produce that 
snazzy, Turbo-charged accounting 
package. 

There’s nothing wrong with this 
method. In fact, it’s the only effec- 
tive way to build competitive, 
commercial-quality applications. 
The other way to build software— 
by gluing together very high-level 
standardized software parts—has 
long been neglected, or else slan- 
dered under the term “prototyp- 
ing,” when in fact it’s just the 
thing when all you really need to 
do is tool up and down the alley. 

As research for a new book I’m 
working on, I’ve been building 
some standardized parts. One of 
them is an editor window that 
incorporates the Borland Binary 
Editor. The window only takes two 
parameters: the filename to be 
edited, and a number from | to 4 
that specifies which fraction of the 
screen to use (whole, half, third, 
or a quarter). When called, the 
window saves the underlying text 
screen to the heap and then pops 
up as far from the cursor as it can. 

Another part is a file picker 
window that only takes two pa- 
rameters: a file spec and a num- 
ber from 1 to 4. When called, it 
works exactly like the editor win- 
dow except that it displays a 
bounce-bar menu of filenames 
that match the file spec. 

Other standardized parts in the 
works include a date field editor, a 
string field editor, a phone num- 
ber field editor, and (with luck) a 
1200-baud telecomm window with 
only two parameters: a number to 
dial, and the 1-4 screen-portion 


value. Designing the parts takes 
some cleverness, but stringing 
them together takes very little. 
The resulting applications are 
“lumpy,” and not especially flex- 
ible, but they work and can be 
created in 20 minutes flat. 

The secret is this: Keep the inter- 
faces simple. Choose reasonable 
defaults and live with them. Also, 
have one part do one thing. A uni- 
versal field editor is far more trou- 
ble than separate ones for strings, 
dates, and integers. 

What I’m reaching for here is 
called object-oriented program- 
ming, best known in specialized 
languages like C++ and Actor, 
but actually approachable in all of 
the Turbo languages. It’s been a 
fascinating project, and I'll share 
my thoughts on it here from time 
to time, publishing some of my 
objects in the Turbo Pascal section 
of TURBO TECHNIX. The built-in 
overhead and inflexibility make 
object-oriented methods iffy for 
commercial applications, but for 
small or inhouse projects, these 
methods can save enormous 
amounts of work. 

Remember, we're not talking 
racing stripes here. If you only 
need a go-kart, why build a 
Porsche? @ 


Opinions expressed in this column are those 


of the editor and do not necessarily reflect 
the views of Borland International, Inc. 


Interlocking Pieces: 


Blaise and 
Turbo Pascal. 


Whether you're a Turbo Pascal expert or a novice, you can benefit from using professional tools 
to enhance your programs. With Turbo POWER TOOLS PLUS™ and Turbo ASYNCH PLUS™ 
Blaise Computing offers you all the right pieces to solve your 4.0 development puzzle. 


Compiled units (TPU files) are provided so each package is ready to use 
_ with Turbo Pascal 4.0. Both POWER TOOLS PLUS and ASYNCH PLUS 


and use units. 


®POWER TOOLS PLUS isa library of over 180 powerful functions 
and procedures like fast direct video access, general screen 
Lan handling including multiple monitors, VGA and EGA 50-line 
and 43-line text mode, and full keyboard support, including 
the 101/102-key keyboard. Stackable and removable win- 
dows with optional borders, titles and cursor memory 
provide complete windowing capabilities. Horizontal, ver- 
tical, grid and Lotus-style menus can be easily incorporated 
into your programs using the menu management routines. 
You can create the same kind of moving pull down menus 
that Turbo Pascal 4.0 uses. 


Control DOS memory allocation. Alter the Turbo Pascal heap 
size when your program executes. Execute any program from 
within your program and POWER TOOLS PLUS automatically 

compresses your heap memory if necessary. You can even force 
the output of the program into a window! 


Write general interrupt service routines for either hardware or 
software interrupts. Blaise Computing’s unique intervention 
code lets you develop memory resident (TSRs) applications 
that take full advantage of DOS capabilities. With simple pro- 

~ cedure calls, “schedule” a Turbo Pascal procedure to execute 
either when pressing a “hot key” or at a specified time. 


@ASYNCH PLUS provides the crucial core of hardware interrupts 
needed to support asynchronous data communications. This package offers 
simultaneous buffered input and output to both COM ports, and up to four 
ports on PS/2 systems. Speeds to 19.2K baud, XON/XOFF protocol, hard- 
ware handshaking, XMODEM (with CRC) file transfer and modem control 
are all supported. ASYNCH PLUS provides text file device drivers so you 
can use standard “ReadIn” and “Writeln” calls and still exploit interrupt-driven 
communication. 


The underlying functions of ASYNCH PLUS are carefully crafted in assembler 
and drive the hardware directly. Link these functions directly to your application 
or install them as memory resident. 


Blaise Computing products include all source code that is efficiently crafted, 
readable and easy to modify. Accompanying each package is an indexed 
manual describing each procedure and function in detail with example 
code fragments. Many complete examples and useful utilities are 
included on the diskettes. The documentation, examples and 
source code reflect the attention to detail and commitment to 
technical support that have distinguished Blaise Computing over 
the years. 


Designed explicitly for Turbo Pascal 4.0, Turbo 
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Turbo POWER SCREEN — $129.00 
NEW! General screen management; paint 
screens; block mode data entry or field-by- 
field control with instant screen access. Now 
for Turbo Pascal 4.0, soon for C and BASIC, 


Turbo C TOOLS $129.00 
Full spectrum of general service utility func- 
tions including: windows: menus; memory 
resident applications; interrupt service rou- 
tines: intervention code; and direct video 
access for fast screen handling. For Turbo C, 


C TOOLS PLUS $129.00 
Windows: menus; ISRs; intervention code: 
screen handling and EGA 43-line text mode 
support; direct screen access; DOS file han- 
dling and more. Specifically designed for 
Microsoft C 5.0 and QuickC. 


ASYNCH MANAGER $175.00 
Full featured interrupt driven support for the 
COM ports. I/O buffers up to 64K; XON/ 
XOFF; up to 9600 baud; modem control and 
XMODEM file transfer. For Microsoft C and 
Turbo C or MS Pascal. 


PASCAL TOOLS/TOOLS 2 $175.00 
Expanded string and screen handling: graph- 
ics routines: memory management; general 
program control; DOS file support and more, 
For MS-Pascal. : 


KeyPilot $49.95 
“Super-batch” program. Create batch files 
which can invoke programs and provide input _ 


to them; run any program unattended:create 
demonstration programs; analyze ie dat uae 


usage. 


EXEC $95.00 
NEW VERSION! Program chaining execu- 
tive. Chain one program from another in 
different languages; specify common data 
areas: less than 2K of overhead. 


RUNOFF $49.95 
Text formatter for all programmers. Written 
in Turbo Pascal: flexible printer control; user- 
defined variables; index generation; and a 
general macro facility. 


TO ORDER CALL TOLE FREE 
800-333-8087 


TELEX NUMBER - 338139 
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on Se Vicrosoft 

OT and QuickC are 

registered trademarks of 


tered trademark of Borland International. 


Are we glowing in the dark, or is 
the smoke pouring out of your 
ears? Errata or accolade? Bug or 
feature? Let us and your fellow 
readers know what's on your 
mind, and our editorial staff and 
authors will respond as best they 
can. 

Address letters to: 


DIALOG 
TURBO TECHNIX Magazine 
4585 Scotts Valley Dr. 
Scotts Valley, CA 95066 


Letters become the property of 
TURBO TECHNIX and cannot 
be returned. We cannot answer all 
letters individually, but we will try 
to print a representative sampling 
of mail received. 


INLINE TEXT 


I would like to commend you on 
one facet of the production of 
your new journal. An article is 
started and then completed with- 
out “interrupts.” Many publica- 
tions give you the first page, fol- 
lowed by “continued on Page 
500,” which can be highly annoy- 
ing. This is one type of GOTO 
statement that I can do without! 


J. M. Anthony Danby 
Raleigh, NC 


When we say we're a structured maga- 
zine, we're not kidding. Once you 
start a TURBO TECHNIX article, 
it’s definitely: 
REPEAT 

Read(APage); 

TurnPage 
UNTIL Done; 


—Jeff Duntemann 
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Dead horses with wheels; and how do 
you pronounce “Dijkstra,” anyway? 


..- AND ONE WITH ALL 
FOUR LEGS 

In the November/December 1987 
issue of TURBO TECHNIX, in the 
article “Turbo Pascal 4.0 Arrives!” 
you say, “The single most impor- 
tant attribute of any software tool 
is speed.” I say: “WRONG. The sin- 
gle most important attribute of 
any software tool is correctness.” 


Frederick D. Portoraro 
Toronto, Canada 


Hey, come on. When I hire a horse at 
a riding stable, I don’t say, “Uh, 
could you make it a live one, please?” 
When we buy tools, we expect them to 
be correct. Minor bugs make us com- 
plain; major bugs send the limping 
nag back to the vendor. You're right, 
of course, and it’s a sad reflection on 
the history of our industry that correct- 
ness is not an unspoken assumption 
in every case. The field is littered with 
the corpses of companies who nailed 
wheels on dead horses and assumed 
we programmers wouldn't know the 
difference. 


—Jeff Duntemann 


WHO’S A HYPERVISOR? 


I read with interest your editorial 
entitled “DOS, The Understood” 
in the January/February 1988 


issue of TURBO TECHNIX. You 
write on Page 5: “In a well- 
integrated 386 machine, DOS, 
plus a hypervisor like Windows/ 
386 or PC-MOS 386, become 
pretty much everything that OS/2 
is: A genuine multitasking OS with 
all the memory it needs.” 

This statement is erroneous. 
Unlike Windows/386, PC-MOS 
386 is not a hypervisor—it is a 
full-fledged multiuser/multitask- 
ing operating system for 80386-, 
80286-, and 8088-based machines. 

Thanks for the opportunity to 
set the record straight. 


Colleen Goidel 

Public Relations Manager 
The Software Link, Inc. 
Atlanta, GA 


Thanks, Colleen. The PC operating 
system scene is getting to be what the 
ancient Chinese philosophers would 
have called “interesting.” Let me take 
a moment to sum it up: Windows/ 
386, DesqView, and IGC’s VM/386 
are 386 hypervisors. All require DOS 
to operate, but DesqView has a mode 
that will operate correctly without a 
386. PC-MOS/386 and Wendin-DOS 
are complete, DOS-compatible operat- 
ing systems. PC-MOS/386 makes use 
of 386 memory management and vir- 
tual 86 partitioning; Wendin-DOS 
does not, although they claim to be 
working on it. And, of course, OS/2 
is... OS/2. Everybody got all that? 


—Jeff Duntemann 
continued on page 8 


Sophisticated User Interfaces in Minutes! 


Put magic in your programs with ¢ 


“rg 
| 


The World’s Best Code Generator! 


Windows for data-entry (with full-featured editing), context-sensitive help, Lotus-style menus, pop- 
up menus, and pull-down menu systems. Overlay them. Scroll within them. 


Users and critics say it all!... 


“.. the best I've used ... The code that it generates is excellent, with every feature you 
could conceivably desire. ... if you have problems, they give excellent technical advice 
over the phone. ... It saves time, is flexible and produces screens which are state of the 
an Sally Stott, Software Developer 


“... the best screen generator on the market.” George Kwascha, TUG Lines, Nov/Dec 87 


“... the Cadillac of prototyping tools for Turbo Pascal. ... Unlike the others, turbo MAGIC 
is extremely flexible. ... [it] clearly offers the greatest variety of options.” 


Jim Powell, Computer Language, Jun 87 


“Fast automatic updating of dependent fields adds flair to your input screens. ... 
turboMAGIC will be a blessing for programmers who would rather not write the user 
interface for every program.” Neil Rubenking, PC Magazine, 24 Feb 87 


“Twas impressed with the turbo MAGIC package. ... the procedures created by turbo MAGIC 
are well commented and easy to add to your own code.” 
Kathleen Williams, Turbo Tech Report, May/Jun 87 


“... definitely a recommended program for any Turbo Pascal programmer, novice or expert.” 
Terry Lovegrove, Library Hi Tech News, Oct 87 


ORDER your Magic TODAY! Only $199. 
CALL TOLL FREE 800-225-3165 or 205-342-7026 


sophisticated 
software 


esd 


6586 Old Shell Road, Mobile, AL 36608 
Requires 512K IBM PC compatible and Turbo Pascal 4.0. 30-Day Money Back Guarantee. Foreign orders add $15. 
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WHERE IT’S @ 


The first two issues of TURBO 
TECHNIX have been full of useful 
stuff. As a user of Turbo Pascal, 
several of the Toolboxes, SideKick, 
SuperKey, Reflex, and—most 
recently—Quattro, I think it’s 
great to have a magazine that spe- 
cializes in articles about Borland 
products. 

The Quattro article in the 
second issue whetted my appetite 
for details of how to add features 
to Quattro. I hope the articles 
are within reach of a less-than- 
superstar Turbo Pascal pro- 
grammer. 

One thing I'd like to do with 
Quattro is add some @ functions 
that correct what I see as deficien- 
cies in some of the existing func- 
tions. Specifically, I'd like to have 
versions of the @COUNT, 
@AVG, @STD, and @VAR func- 
tions that count only cells with 
numbers or formulas in them and 
ignore cells with text. 

If these functions ignore text 
cells then you can include text 
column headings or dotted lines, 
etc., at the top and bottom of the 
blocks you want counted or aver- 
aged. That way, you can add rows 
of data anywhere in your current 
data columns and have correct 
counts and averages. SuperCalc 
4’s COUNT and AV functions 
ignore text cells, by the way. 

If the future article that de- 
scribes how to add @ functions to 
Quattro is not written yet, would 
you consider using as an example 
an @COUNT or @AVG function 
that passes over text cells? I would 
appreciate this very much! 


Sam Baker 
Columbia, SC 


The idea is not to publish only one 
article on building your own Quattro 
@ functions. We will be publishing 
custom @ functions regularly, along 
with other kinds of Quattro add-ins, 
in both Turbo C and Turbo Pascal. 
Like every other kind of programming, 
writing Quattro @ functions takes 
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some close attention and practice, but 
much of the hard work is already done 
by virtue of Quattro’s internals being 
available as callable routines. An 
introductory article on @ functions in 
our next issue will get you started, 
and I'll pass along your requests to 
our other authors who will be writing 
about @ functions in future issues. 


—Jeff Duntemann 


DEFENDING BASIC 


I really enjoyed both of Bruce 
Webster’s articles in TURBO 
TECHNIX, January/February 
1988, and they were (mostly) accu- 
rate and right on the money. His 
illustration showing how all of the 
fancy control structures are noth- 
ing more than GOTOs in disguise 
was masterful. However, I'd like to 
add a few comments. 

In “Thinking in C,” Bruce 
praises C for its conciseness in 
allowing statements such as 
c=(a>b)? a:b; 
and 
while ((lineLindx++] = 

tupper(getc(infile))) != EOF) 
as if this were some really nifty 
feature that BASIC does not pro- 
vide. He then goes on to deride 
BASIC as having “very little form: 
it’s just a collection of numbered 
statements.” Further, in “Binary 
Engineering,” Bruce concludes 
that GOTO should be used spar- 
ingly, and then only when 
necessary. 

Let’s face it folks—you can write 
terrible code in ANY language. 
There is nothing inherent in 
BASIC that would encourage poor 
programming, or make tracing a 
program’s flow any more 
difficult than in another language. 
Real-world programs use proce- 
dures that call other procedures, 
and C or Pascal really offer no 
better protection against making a 
mess of things. 

Legitimate complaints against 
BASIC might be that the BASICA 
interpreter is slow and has a 
clumsy line editor, or that most of 
the current compilers make .EXE 
files that are too large. But to say 
that BASIC encourages “spaghetti 
code” or that using GOTO is a 
poor practice simply isn’t true. Of- 
ten, attempting to avoid all use of 
a GOTO simply results in code 
that is harder to read. 


For example, suppose you want 
to pause until a user presses a key. 
In BASIC it is often done like this: 


WHILE INKEYS = "": WEND 


This is a perfect use of 
WHILE..WEND, and it avoids the 
need for both a GOTO and, more 
important, an extra line label. But 
suppose you also need to know 
which key was pressed. I’ve often 
seen it done this way 


x$ = uu 
WHILE X$ = "" 
X$ = INKEYS 

WEND 


PRINT "You pressed the " X$ "key" 


where X$ must first be cleared, 
just to insure that the WHILE will 
execute at least once. Here, using 
a GOTO is decidedly clearer, 
while creating less code in the 
bargain: 

GetKey: 

xX$ = INKEYS 

IF X$ = "" GOTO GetKey 
This is a simplistic example for 
sure, but it illustrates what often 
results when a programmer 
attempts to shoe-horn “structure” 
into a situation where none is 
called for. With all due respect, 
Edsger Dijkstra seems like the pro- 
grammer’s equivalent of Archie 
Bunker. 

BASIC lets you write very com- 
pact code too when you want. 
Similar to Bruce’s examples, you 
might do this in BASIC 


X = ABS(Y * (Z > 9)) 
or: 


WHILE 
UCASE$( INPUT$(1, #1) )<>CHR$(13) 
WEND 
BASIC also lets you call DOS and 
BIOS functions incorrectly, or 
overwrite the operating system— 
just like C does. Indeed, BASIC is 
a powerful and capable language, 
GOTOs and all. 
Ethan Winer 
Crescent Software 
East Norwalk, CT 
Thus flares up a debate that has 
raged for some years. I agree that it is 
possible to write atrocious code in C or 
Pascal; having taught an “Intro to 
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Programming” class at a university 
for a few years made that all too clear. 
And I have seen some beautifully 
structured code written in BASIC. 
However, the proper question (to 
paraphrase C.S. Lewis) is how much 
worse the code written by the first 
group would be if done in BASIC, or 
how much better the code done by the 
second group would be if written in C 
or Pascal. 

Ethan, I agree with your assertion 
that “attempting to avoid all use of a 
GOTO simply results in code that is 
harder to read” —provided we're dis- 
cussing BASIC, which has a very 
limited set of control structures. Given 
the richer and more complex set of con- 
trol structures in C and Pascal, there 
is little need or use for GOTO state- 
ments, and they are not so much 
avoided as simply ignored. 

TI will also agree that BASIC has 
improved vastly since its early days, 
mostly by shamelessly borrowing from 
Pascal, C, and FORTRAN such posi- 
tive constructs as WHILE..WEND 
statements, block IF..THEN state- 
ments, alphanumenc labels, unlabeled 
statements, and parameters to subrou- 
tines. The result is code that looks sus- 
piciously like a mixture of Pascal, C, 
and FORTRAN. I just prefer to skip 
the new, improved BASIC and go 
with the real thing. 

As for Edsger Dijkstra, here’s a 
quote (based on the old, unimproved 
BASIC) which should really make 
your day: “It is practically impossible 
to teach good programming to stu- 
dents that have had a prior experience 
in BASIC: as potential programmers, 
they are mentally mutilated beyond 
hope of recognition.” (Selected Writ- 
ings, p. 130) 

—Bruce Webster 


OS/2 ASCENDANT 

Impossible for OS/2 to replace 
DOS, you say? Think again. Look 
at the history of Digital Research’s 


CP/M. More than five years ago 
CP/M was the OS for microcom- 


puters, mostly for Z80 machines. 
Then what happened? IBM rolled 
out its PC, initially offering two 
OS’s: CP/M-86 and something 
brand new called PC-DOS. 

Although CP/M was the stan- 
dard of the day (supporting such 
staples as WordStar, SuperCalc, 
and dBase II, and even had a 
multitasking version, MP/M), 
IBM’s practically giving DOS away 
at $70 per copy, along with its 
technical superiority and excellent 
documentation, rapidly made 
DOS the favorite OS of the PC. 
With its expensive pricing, its 
crude documentation, and user- 
hostile error handling, CP/M was 
a throwback to the Bad Old Days 
of computer systems that Mr. 
Duntemann seems to recall with 
distaste. For awhile, software 
developers supported both OS’s. 
The final blow to CP/M-86, how- 
ever, came from neither Microsoft 
nor IBM. It came from Lotus 
Development, which offered its 
1-2-3 spreadsheet product in DOS 
format only. The success of 1-2-3 
made CP/M compatibility 
irrelevant. 

I believe that history may repeat 
itself. OS/2 and its successors are 
likely to become the PC standards 
that take us into the 1990s. As 
such, OS/2 will kill off plain old 
DOS, just like DOS finished off 
CP/M several years ago. DOS will 
become obsolete when software 
developers offer (and the PC mar- 
ket accepts) their next-generation 
blockbuster applications in OS/2 
and Presentation Manager for- 
mats only. 

Software developers—and PC 
pundits—should encourage, 
rather than discourage, the devel- 
opment of such needed standards 
as OS/2. At this stage, those who 
choose to ignore OS/2 do so at 
their own peril. 

—Kenneth C. Kmack 
Lilburn, GA 


You called it, right there in your last 
paragraph. The Z80 industry was 
crippled out of the gate by its lack of 
hardware standards. IBM’s PC blew 
the Z80 away because the PC provided 
a standard hardware environment, 
and with the Z80 went DRI’s fortunes 
and CP/M in general. CP/M-86 and 
DOS 1.0 were just about identical. 
Both had awful documentation and 
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cryptic error handling (which DOS 
still has). DOS was cheaper (I think 
more like $40, wasn't it?), but no 
better. 

History will not repeat itself this 
time for several reasons. There are ten 
million 8088 machines out there, 
none of which will ever run OS/2. 
Tens of thousands more roll in from 
the Far East every day, and sell for 
$500 each. That’s more than critical 
mass, that’s supercritical. 

OS/2 is by no means being given 
away. Cost does matter. Furthermore, 
the current DRAM shortage and price 
hikes could put a crimp in OS/2’s 
early acceptance by making the neces- 
sary 2-4MB of RAM costly and hard 
to find. Presentation Manager is cniti- 
cal in many areas, especially software 
portability, and if PM does not find 
acceptance, OS/2 won't either. PM 
will be successful on the new genera- 
tion 386/486 machines ... but on the 
slower mainstream 286 boxes, it’s still 
a very open question. 

I'm flattered to see that I’ve finally 
made the rank of pundit. I haven't 
been so flattered since I was at a beer 
bust back at DePaul University, and 
an earnest young woman told me in 
disbelief, “You always talk in com- 
plete sentences!” 


—Jeff Duntemann 


Have you written a major appli- 
cation using one of Borland’s 
programming products? If so, 
Borland Product Communica- 
tions would like to hear about 
it. Send a letter describing your 
product, along with any market- 


ing copy relating to the pro- 
duct, to: 
Bill Burch 
Borland International 
4585 Scotts Valley Drive 
Scotts Valley, CA 95066-0001 
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It doesn't matter which language you pro- 
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minutes! That's right. Truly 
fantastic screens for menus, 
data entry, data display, and 
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with as little as one line of code in any 
language. Batch files, too. 

With Saywhat, what you see is 
exactly what you get. And response time 
is snappy and crisp, the way you like it 
That means screens pop up instantly, 
whenever and wherever you want them 

Whether you're a novice program- 
mer longing for simplicity, oraseasoned 


30 days for 


professional searching for higher produc- y 7» 
tivity, you owe it to yourself to check out (FZ . 
Saywhat. For starters, it will let you build a 


your own elegant, moving-bar menus into i Ae 

: ae \ 
any screen. (They work like magic in any /)) ) 
application, with just one line of code!) ELLL 
You can also combine your screens into extremely 
powerful screen libraries. And Saywhat's remarkable 
VIDPOP utility gives all languages running under PC 
MS-DOS, a whole new set of flexible screen handling 
commands. Languages like dBASE, Pascal, BASIC, C, 
Modula-2, FORTRAN, and COBOL. Saywhat works with 
all the dBASE compilers, too! 

With Saywhat we also include a bunch of terrific 
utilities, sample screens, sample programs, and out- 
standing technical support, all at no extra cost. (Com- 
prehensive manual included. Not copy protected. No 
licensing fee, fully guaranteed). $49 95 
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If you aren't completely 
delighted with Saywhat or 
Topaz, return them within 
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The breakthrough ~——; 
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Turbo Pascal 4.0 


bie 


If you'd like to combine the raw power and 
speed of Turbo Pascal with the simplicity and 
elegance of dBASE, Topaz 
is just what you're looking 
for. You see, Topaz (our 
brand new collection of 
units for Turbo Pascal 4.0) was specially 
created to let you enjoy the best of both 
worlds. The result? You can create truly 
dazzling applications in a very short 
time. And no wonder. Topaz is a compre- 
hensive toolkit of dBASE-like commands 
a prompt, and functions, designed to help you 

WS create outstanding, polished programs, 

by fast. Think of it. With Topaz you can write 

Pascal code using SAYs and GETs, 
PICTURE and RANGE clauses, then SELECT and USE 


\| databases (real dBASE databases!), SKIP through 


records, APPEND data, and lots more 

In fact, we've emulated over one hundred actual 
dBASE commands and functions, and even added new 
commands and functions to enhance the dBASE 
syntax! All you have to do is declare Topaz’s units in 
your source code and you're up and running! 

The bottom line? Topaz makes writing sophisti- 
cated Pascal applications a snap. Data entry and data 
base applications come together with a minimum of 
code and they'll always be easy to read and maintain. 

Topaz comes with a free code generator that auto- 
matically writes all the Pascal code you need to 
maintain a dBASE file with full-screen editing. Plus 
outstanding technical support, at no extra cost. (Com- 
prehensive manual included. Not copy protected. No 
licensing fee, fully guaranteed). $49.95 


ORDER NOW. YOU RISK NOTHING. Thousands of satisfied users have already ordered from us. Why not call toll-free, right 
now and put Saywhat and Topaz to the test yourself? They're fully guaranteed. You don't risk a penny. 


SPECIAL LIMITED-TIME OFFER! Buy 
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$85 (plus $5 shipping & handling). 
That's a savings of almost $15. 
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TURBO PASCAL 


MEET THE BGI 


Discover the new frontier of Turbo Graphics by taking a 
guided tour of the Borland Graphics Interface. 


Tom Swan 


Until recently, IBM PC color graphics 
were about as exciting and colorful as 
dried mud. Graphics programmers were 
ie well advised to purchase a Macintosh II, 
Amiga, or Atari—anything but a PC. 

Today, EGA (Enhanced Graphics Adap- 
ter) and VGA (Virtual Graphics Array) displays are 
putting a new face on PC graphics programming. 
Combined with the new Borland Graphics Interface 
(BGI), these display modes offer a fresh frontier for 
PC pioneers to conquer. 

An easy way to join the graphics wagon train is to 
hitch Turbo Pascal 4.0 or Turbo C 1.5 to your trusty 
computer. These new compiler versions come 
equipped with interfaces to the Borland graphics 
kernel, a machine language wagon master that man- 
ages a herd of PC graphics display modes with ease. 

This introductory guided tour of the BGI covers a 
wide range of terrain in order to provide you with a 
feeling for the scope of BGI graphics capabilities. At 
many of the stops, we'll just scratch the surface— 
further travel is left to you. Although the tour con- 
centrates on Turbo Pascal’s BGI interface, much of 
the following introduction to BGI graphics applies to 
Turbo C as well. 


A KERNEL OF BEAUTY 


The word kernel usually refers to the part of an oper- 
ating system that runs in supervisor mode, resolving 
conflicts, granting access to disks and other devices, 
and making sure the dirty work gets done. In BGI 
graphics, the kernel is the central core that initializes 
the screen, draws lines and shapes, displays text, and 
performs other graphics-related functions. 

The Borland graphics kernel is identical (or at 
least nearly so) in both Turbo Pascal and Turbo C. 
Each language provides a graphics interface, which 
allows you to use the items in the kernel. The graph- 
ics interface specifies the calling syntax of the kernel’s 
routines, and defines the kernel’s data structures. In 
Turbo Pascal, the graphics interface is stored in the 
file GRAPH.TPU; in Turbo C, the graphics interface 
is in the header file, GRAPHICS.H. 


SQUARE ONE 
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USING BGI GRAPHICS 


To use BGI graphics in Turbo Pascal, construct your 
program like this: 


PROGRAM MyGraphics; 
USES Graph; 


BEGIN 
{ Graphics commands } 
END. 


The USES Graph; statement tells the compiler to 
load the GRAPH.TPU unit, making that unit’s con- 
stants, types, variables, procedures, and functions 
available to your program. Turbo C programmers 
might want to print a copy of GRAPHIC.H for refer- 
ence to the many BGI commands and structures. 
Turbo Pascal users can print GRAPH.DOC, a 
text guide to the compiled GRAPH.TPU unit. 
GRAPH.DOC also lists last-minute corrections to 
the BGI information in the Turbo Pascal Owner’s 
Handbook. 


THE DRIVER AND FONT FILES 


BGI graphics driver code is stored in files ending in 
-BGI. Each .BGI file contains hardware-specific code 
for driving a particular kind of display device (see 
Table 1). When you run a graphics program, the cor- 
rect .BGI file is loaded into memory; therefore, the 
driver file must be in a location known to the graph- 
ics program when it is run. You need the BGI inter- 
face code—either GRAPH.TPU for Turbo Pascal or 
GRAPHICS.H for Turbo C—only when compiling 
graphics programs. You need the .BGI driver files 
only when running these same programs. 

Usually, it’s best to store all .BGI files in the direc- 
tory that contains the Turbo Pascal or Turbo C com- 
piler. If you’re short on disk space, though, use Table 
1 as a guide while deleting all files except the file 
that you need for your own system. 


Another kind of graphics file, 
ending in .CHR, contains data 
that allows the display of text in 
a variety of styles, or fonts. I'll 
explain more about fonts in a 
moment. For now, make sure you 
have the .CHR files (listed in 
Table 2) in your Turbo Pascal or 
Turbo C directory. As with .BGI 
files, you need .CHR files only 
when running graphics programs, 
not when compiling them. 


INITIALIZING GRAPHICS 
MODES 


The first step in every graphics 
program is to initialize a graphics 
mode using one of three methods: 
automatic, semiautomatic, or man- 
ual. The automatic method detects 
the type of graphics hardware on 
your system and then selects a 
graphics mode that produces the 
best results (usually a mode with 
the highest supported resolution). 
The semiautomatic method auto- 
matically detects the installed 
graphics hardware, but allows you 
to choose a display mode manu- 
ally. The manual method lets you 
write programs that demand spe- 
cific display hardware and graph- 
ics modes. 

All three initialization methods 
require three global integer 
variables: 

VAR 
grDriver, 


grMode, 
grError : Integer; 


Integer grDriver represents a 
.BGI driver by number (see Table 
1), The grMode variable repre- 
sents the mode for this driver, 
thereby selecting a display resolu- 
tion and, for some drivers, a set 
of colors. (Most drivers support 
several different modes. Refer 
to your Turbo language refer- 
ence manuals and the files 
GRAPH.DOC and GRAPHICS.H 
for the mode constants you can 
assign to grMode.) The grError 
variable holds error codes re- 
turned by several graphics 
routines. 

Automatic initialization. To auto- 
matically detect and initialize a 
graphics display, first assign the 
constant Detect to grDriver. Then 
call InitGraph: 


continued on page 16 
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DESCRIPTION 


EGA64 
EGAMono 
Reserved 
HercMono 
ATT400 
VGA 
PC3270 


Table 1. BGI graphics drivers. 
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Color Graphics Adapter 
Multicolor Graphics Array 
Enhanced Graphics Adapter 
64K EGA 

Monochrome EGA 

none 

Hercules Monochrome Graphics 
AT&T 400-line graphics 

Video Graphics Array 

IBM PC 3270 Graphics 


DISK FILE 


CGA.BGI 
CGA.BGI 
EGAVGA.BGI 
EGAVGA.BGI 
EGAVGA.BGI 
none 
HERC.BGI 
ATT.BGI 
EGAVGA.BGI 
PC3270.BGI 
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Buy Our Tools, And We’ 


Introducing Emerald Bay. The 
breakthrough database server 
technology for developing single 
and multi-user applications. 
Emerald Bay provides your pro- 
grams a common data storage 
and retrieval method which 
allows data to be transparently 
shared across multiple and 
diverse applications. 

And when you buy one of our 
tools for “C’? dBASE” or Lotus" 
developers, we'll give you the per- 
sonal engine—free. No royalties 
to pay, no licenses to sign. 

Developed by Wayne Ratliff, 
the creator of dBASE, Emerald 
Bay is much more than just 
another DBMS product, it’s an 
entirely new way to manage data. 
It's designed to provide an open 
platform for developing applica- 
tions in several languages and 
environments, while Emerald 
Bay maintains data security, 
concurrency and integrity. 

How The Engine Works 

Before, data couldn't be readily 
shared between applications. 
But with Emerald Bay, PC appli- 
cations each share a common 
data storage and retrieval 


— » 
} 


-”. 


method. And although the func- 
tions of the applications may 
vary widely, any one application 
can share another’s data trans- 
parently; there is no data conver- 
sion or translation necessary. 
When a PC is an intelligent 
workstation on a LAN, the 
Emerald Bay database server 
technology controls all data 
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Emerald Bay Architecture 


OPERATING SYSTEM 


security and integrity, including 
transaction logging with roll- 
back. An application simply 
makes a request, which is sent 
to the engine. There, only the 
essential data is sent back to the 
workstation. The result is vastly 


reduced network traffic and 
faster data access times. 

How You Work With 

The Tools 

' With the tools we pro- 

' vide, you can easily develop 
Emerald Bay applications 


immediately in your familiar 


development environment. 

Emerald Bay technology 
handles the usually code- 
intensive management of data, 
so you can concentrate on 
what you do best—developing 
applications. 

The Developers Toolkit for “C” 
includes well-documented, easy 
to use “C” libraries that give you 
the power to create advanced 
applications, without the effort 
usually associated with design- 
ing and coding a database 
“backend” 

Eagle is Emerald Bay's sophis- 
ticated dBASE-like program- 
ming language. As the logical 
evolution of database language, 
Eagle introduces advanced fea- 
tures, routines and language 
components, including a com- 
piler, network commands, user- 
defined functions in “C” and 
Assembly and automatic index 
maintenance. 

Summit is an “add-in” data- 
base management system for 
Lotus 1-2-3, which gives you 
sophisticated data manipulation 
and analysis commands. All 
three of Emerald Bay’s develop- 
ment tools come with the Core 
Components which include 
Report Writer, Forms Generator, 


© Migent, Inc., Registered trademarks: dBase (Ashton-Tate), Lotus and 1-2-3 (Lotus Development Corp.), OS/2 (International Business Machines, Corp.), Macintosh (Apple Computer, Inc.), Unix (AT&T). 


ll Give You 


an Import/Export facility and 
the Database Administrator. 

The Emerald Bay Database 
Server is the heart of the multi- 
user Emerald Bay technology. Its 
client/server architecture is 
superior to current implementa- 
tions of LAN/DBMS products, 
and increases total system 
throughput, while reducing net- 
work traffic and access times. 

Finally, while providing a path 
to other operating systems such 
as OS/2, Macintosh and UNIX, 
Emerald Bay is a microcomputer- 
based technology that optimizes 
your current hardware 
investment. 

Free Technical Seminars 
We're hosting a series of 


The Engine. 


Emerald Bay Engine Specifications 


. Data Storage Security And Integrity Features 
tree Emerald Bay Tech nical - Max. databases No limit - Access permissions by Read, Write, 
Seminars during April and May - Max. tables per database 1000 _ Delete, Add and Grant 


in cities across the country. It’s 
your chance to see Wayne Ratliff 


- Max. fields per table 800 
- Max. field width 


512 characters 


- All five access permissions work on 
tables and objects 


e t ik lit; f + Max. records per table Nolimit + Read, Write and Grant access per- 
emonstrate the capabilities 0 -Max. width of records 10,000 bytes _ missions operate at field level 
Emerald Bay in person, as well (no limit on ext. fields) - All data other than binary fields can 
as get some practical experience - Max. open databases 7 (MS-DOS beencrypted ; 
limitation) - Transaction logging, with commit and 


with the technology yourself. 

Call us toll-free at 
1-800-777-2027 (and ask for 
Sandra) for the date and loca- 
tion of the seminar nearest you. 
Space is limited, so be sure to 
reserve your seat today. 

Emerald Bay. Advanced 
database server technology. 
Available now 


Index Storage 


- Composite keys supported 

- Mixed data type keys allowed 

- Keys of up to 100 bytes in length 

- Automatic index maintenance 

- Ascending and descending keys 

* Case independent keys 

- Automatic table indexing on record 


number 


rollback functions 

: Full security functions at field and 
table level 

: Optional data encryption at field level 

System Requirements 

- MS-DOS 3.1 or greater 

- Network database server or Single- 
user computer: PC XT, AT, PS/2 or 386 
compatible, 640K, Hard Disk 

- Workstation on LAN: PC, XT, AT, PS/2 
or 386 compatible, 640K 

- NetBIOS compatible networks 
supported 


DEVELOPERS 
TOOLKIT 


GPM RIP MIG=NT 
BAY —_ 
Mt 865 Tahoe Blvd., Call Box 6, Incline Village, NV 89450 


Trademarks pending: Emerald Bay, Eagle, Summit (Migent, Inc.) 


FONT NAME NUMBER 
DefaultFont 
TriplexFont 
SmallFont 
SansSerifFont 
GothicFont 


mono 


Table 2. BGI fonts. 
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continued from page 13 


grDriver := Detect; 
InitGraph( grDriver, grMode, '' ); 


The first two parameters to 
InitGraph are the integer vari- 
ables, grDriver and grMode. 
Because grDriver equals Detect, 
InitGraph automatically deter- 
mines the type of graphics hard- 
ware installed on your computer, 
loads the appropriate .BGI driver, 
and selects a default display mode. 
InitGraph returns values in 
grDriver and grMode that repre- 
sent the selected display driver 
and mode. You'll want to preserve 
these values, especially if you plan 
to switch between text and graph- 
ics screens during program 
execution. 

The third parameter to 
InitGraph is a string specifying 
the directory path where you store 
your .BGI driver files. Use a null 
string (two single quotes with no 
space between them) if your .BGI 
files are in the same directory 
as the running program. If you 
store your .BGI files else- 
where (for example, in 
C:\TPAS\GRAPHICS), pass 
the pathname to InitGraph: 

grDriver := Detect; 
InitGraph( grDriver, grMode, 

'C:\TPAS\GRAPHICS' ); 

If all goes well, the screen 
should now be clear and ready 
for graphics commands. To be 
certain of this, check function 
GraphResult, which returns an 
error code for the most recent 
graphics operation (see Table 3). 
All error values are negative 
except for 0, thus indicating that 
no error has occurred. 

GraphResult resets itself and, 
therefore, returns a valid number 
only once after a graphics opera- 
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TYPE DISK FILE 
Bit map none 
Stroked TRIP.CHR 
Stroked LITT.CHR 
Stroked SANS.CHR 
Stroked GOTH.CHR 


tion that returns an error code. 
To preserve the error code value, 
assign GraphResult to the integer 
variable grError immediately after 
a graphics operation. To display 
an English language error mes- 
sage rather than a cryptic error 
code number, pass grError to 
string function GraphErrorMsg 
in a Writeln statement. 
GraphErrorMsg inserts file- 
names in the empty parentheses 
for error codes such as -3 and -4. 
Figure 1 lists the full automatic 
initialization sequence, complete 
with error detection. Because 
grDriver equals Detect, InitGraph 
automatically detects and initial- 
izes a graphics display mode, load- 
ing the appropriate driver into 
memory. After InitGraph, assign 
GraphResult to integer variable 
grError. If grError does not 
equal the constant grOk (see 
Table 3), then an error occurred 
during initialization. If this is 
the case, pass grError to 
GraphErrorMsg in a Writeln 
statement to display an error mes- 
sage along with your heartfelt re- 
grets. If no error is detected, 
you're ready to roll. 


Semiautomatic initialization. The 
semiautomatic initialization se- 
quence is a variation on the auto- 
matic initialization theme. 


ERROR 
CONSTANT CODE 
grOk 0 
grNoInitGraph -1 
grNotDetected -2 
grFileNotFound -3 
grInvalidDriver -4 
grNoLoadMem -5 
grNoScanMem -6 
grNoFloodMem -7 
grFontNotFound -8 
grNoFontMem -9 
grInvalidMode -10 
grError -ll 
grlOerror -12 
grInvalidFont -13 
grInvalidFontNum -14 
grInvalidDeviceNum -15 


Table 3. BGI error codes and messages. 


First, call procedure DetectGraph 
with two integer variable para- 
meters: 


DetectGraph(grDriver, grMode); 


After DetectGraph executes, 
grDriver and grMode contain 
values representing the driver 
and display mode values that 
InitGraph returns when automati- 
cally detecting and initializing 
graphics modes. After inspecting 
grDriver, you can change grMode 
to a different value, thereby select- 
ing an alternate mode for the 
detected driver by calling 
InitGraph. 

For example, let’s use the 
initialization sequence in Figure 
2 to select 640 X 200-resolution 
CGA or MCGA modes. After exe- 
cuting DetectGraph, assign an 
appropriate mode constant to 
grMode. In this case, assign either 
CGAHi or MCGAMed, which 
selects an alternate mode instead 
of the usual defaults. Now, when 

Driver does not equal either 
CGA or MGGA, the program halts 
with an error message. Otherwise, 
grDriver and the modified 
grMode are passed to InitGraph, 
completing the semiautomatic 
initialization. 

Manual initialization. The third 
and final way to initialize graphics 
is to forego automatic device 
detection altogether and to assign 
values directly to grDriver and 
grMode for specific graphics 
hardware. To initialize EGA 640 
X 350 16-color, 2-page graphics, 
write the following code 
sequence: 


MESSAGE 


No error 

(BGI) graphics not installed 
Graphics hardware not detected 
Device driver file not found () 
Invalid device driver file () 

Not enough memory to load driver 
Out of memory in scan fill 

Out of memory in flood fill 

Font file not found () 

Not enough memory to load font 
Invalid graphics mode for selected 
driver 

Graphics error 

Graphics I/O error 

Invalid font file () 

Invalid font number 

Invalid device number 


grDriver := EGA; 
grMode := EGAHi; 
InitGraph(grDriver, grMode,''); 

With this kind of initialization, 
the program runs only on hard- 
ware that supports this particular 
EGA multipage mode. (One page 
equals the amount of memory 
required to hold a single graphics 
screen. Some drivers and modes 
support multiple pages; others 
support only one.) 

Be careful when manually 
initializing graphics. On some sys- 
tems, selecting nonexistent modes 
can lock up the computer, forcing 
you to reboot. For these reasons, 
use automatic and semiautomatic 
initialization methods whenever 
you can—they help you write pro- 
grams that run on the widest pos- 
sible range of PCs. 


TOOLS OF THE BGI ARTISAN 


With initialization out of the way, 
you're ready to begin using all of 
the BGI’s many graphics routines. 
’ There’s more to BGI graphics 
than I can possibly cover in a sin- 
gle article, but the following will 
give you a running start. 

Listing 1 (RANDOMGR.PAS) 
lets you experiment with BGI 
graphics by using a “replaceable” 
procedure to perform the 
graphics drawing activity. Pro- 
cedure DoGraphics contains a 
REPEAT..UNTIL loop, which 
cycles until you press a key. The 
ReadKey statement just before the 
end of DoGraphics clears this 
keystroke from memory. 


grDriver := Detect; 
InitGraph( grDriver, grMode, '' ); 
grError := GraphResult; 
IF grError <> GrOk 
THEN Writeln( 'Graphics error : 
ELSE DoGraphics; 


Figure 1, Automatic BGI initialization. 


DetectGraph( grDriver, grMode ); 
IF grDriver = CGA THEN grMode : 


CGAHi 


The actual drawing commands 
are inside the REPEAT..UNTIL 
loop. In the version of 
RANDOMGR shown as Listing 1, 
two commands select colors and 
then draw colored lines at ran- 
dom, quickly filling the screen 
with an assortment of colored 
lines. To slow the action, insert 
the statement Delay(150); between 
REPEAT and SetColor. For 
debugging, you can use similar 
delays in order to watch complex 
graphics sequences display them- 
selves to the screen in slow 
motion. 

Throughout this article, 
you'll encounter replacement 
DoGraphics procedures consisting 
of article figures that draw graph- 
ics other than lines. By replacing 
the original DoGraphics with one 
of these other procedures, you 
can see a broad sampling of BGI 
graphics in action with minimal 
fuss. The replacement procedures 
are collected in a file called 
GPROCS.SRG, which is contained 
in the CompuServe download file 
PASBGI.ARC. 

Ending graphics programs. Be- 
fore ending your graphics pro- 
grams, always call CloseGraph in 
the manner shown near the bot- 
tom of Listing 1. CloseGraph re- 
stores the display mode that was in 
effect before the call to InitGraph, 
and removes the graphics kernel 
from memory. This prevents leav- 
ing the display in graphics mode. 

If you want to return to graph- 
ics mode after you've called Close- 
Graph, but you haven’t ended 
execution of your program, you 
must again call InitGraph to 
reload and initialize the graphics 
kernel. 


', GraphErrorMsg( grError ) ) 


ELSE 


IF grDriver = MCGA THEN grMode := MCGAMed ELSE 


BEGIN 


Writeln( 'Requires CGA or MCGA graphics' ); 


Halt 
END; { if } 
InitGraph( grDriver, grMode, '' ); 


Figure 2. Semiautomatic BGI initialization. 


Colors and lines. SetColor takes a 
value from 0 to n, selecting from 
among n+1 colors for subsequent 
drawing commands. The maxi- 
mum color value n is different for 
various display modes, but is 
always within the range 0..15. 

To find the maximum value for 
your system, call function 
GetMaxColor. Listing 1 uses this 
technique to generate random 
values from 1 to GetMaxColor, 
selecting among all possible hues 
except 0, which is the background 
color (usually black). 

LineTo takes two integer 
parameters that represent the (x,y) 
coordinate of one display pixel. A 
pixel is the smallest graphics ele- 
ment you can display—a single 
dot, the quark of computer graph- 
ics. LineTo connects two pixel 
locations anywhere in the current 
viewport, which is the currently 
usable display area. The first loca- 
tion is called the Current Point 
(CP); the kernel remembers this 
location at all times. The second 
location is given by the coordinate 
pair passed to LineTo as its two 
integer parameters. Many graph- 
ics commands use CP as a starting 
point, initialized by InitGraph to 
(0,0) in the upper left corner. 
LineTo connects CP to the passed 
(x,y) parameters. After drawing, 
the line’s end becomes the new 
CP; each subsequent line drawn 
with LineTo begins where the 
previous line ends. 

Two other functions in Listing 
1 help the program run correctly 
in all display modes. Function 
GetMaxX returns the maximum x 
(horizontal) coordinate value for 
the current graphics mode. Func- 
tion GetMaxY returns the maxi- 
mum y (vertical) value. Together, 
these two integer functions let you 
write programs that automatically 
adjust for different display 
resolutions. 


More about lines and pixels. By 
modifying Listing 1, you can 
experiment with many other BGI 
commands such as Line, which 
connects two coordinates (xl,y1) 
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PROCEDURE DoGraphics; 


VAR ch : Char; 
xmax, ymax : Integer; 


BEGIN 
xmax := GetMaxX + 1; 
ymax := GetMaxY + 1; 
REPEAT 
Delay(150); 
SetColor( 1 + Random( GetMaxColor ) ); { Select color } 
Line( Random( xmax ), Random( ymax ), € xt, ‘yi 3 
Random( xmax ), Random( ymax ) ); { x2, y2 } 
UNTIL Keypressed; 
ch := Readkey 
END; { DoGraphics } 


Figure 3. Line demonstration procedure replacing DoGraphics in Listing 1. 


PROCEDURE DoGraphics; 


VAR ch : Char; 
xmax, ymax : Integer; 


BEGIN 
xmax GetMaxX + 1; 
ymax := GetMaxY + 1; 
REPEAT 
SetFillStyle( 1 + Random( 11 ), { pattern } 
1 + Random( GetMaxColor ) ); { color } 
Bar( Random( xmax ), Random( ymax ), €x4, ytd 
Random( xmax ), Random( ymax ) ); { x2, y2 } 
UNTIL Keypressed; 
ch := Readkey 
END; { DoGraphics } 


Figure 4. Filled bar demonstration procedure replacing DoGraphics in 
Listing 1. 
PROCEDURE DoGraphics; 


VAR ch : Char; 
xmax, ymax : Integer; 


BEGIN 
xmax := GetMaxX + 1; 
ymax := GetMaxY + 1; 
REPEAT 


SetColor( 1 + Random( GetMaxColor ) ); 
Arc( Random( xmax ), { X coordinate value } 
Random( ymax ), { Y coordinate value } 
Random( 361 ), { Start angle } 
Random( 361 ), { End angle } 
Random( 50 ) ); { Radius } 
UNTIL Keypressed; 
ch := Readkey 
END; { DoGraphics } 


Figure 5. Arc demonstration procedure replacing DoGraphies in Listing 1. 


MEET THE BGI 
continued from page 17 


and (x2,y2). Unlike LineTo, Line 
ignores CP. To see how Line 
works, replace DoGraphics in List- 
ing 1 with the procedure in Figure 
3. When you run the modified 
program, random lines are no 
longer connected end for end. 
Take out the Delay statement to 
shift the program into high gear. 

Figure 3 adds two new integer 
variables, xmax and ymax. Before 
the REPEAT..UNTIL loop begins, 
the program assigns these vari- 
ables the maximum coordinate 
values of the current graphics 
mode, plus 1. Because the display 
resolution is constant, the pro- 
gram runs faster by performing 
these additions outside the loop. 
Also, assigning values to variables 
avoids repeated calls to GetMaxX 
and GetMaxyY. Small tricks such as 
these contribute to making graph- 
ics programs (and other kinds of 
programs, too!) run as fast as 
possible. 

To display individual pixels, use 
PutPixel. Remove the statements 
between REPEAT and UNTIL 
from Figure 3 and insert the fol- 
lowing for a colored confetti 
display: 

PutPixel (Random(xmax), 
Random(ymax ), 
Random(GetMaxColor + 1 )) 

PutPixel takes three parame- 
ters: integer x and y coordinate 
values, and a color value from 0 to 
GetMaxColor. Unlike Line and 
LineTo, PutPixel does not use the 
color value passed to SetColor. 
For the reasons mentioned 
above, you’d be smart to assign 
GetMaxColor+1 to an integer 
variable and then move this addi- 
tion outside the REPEAT..UNTIL 
loop. 


Rectangles. Procedure Rectangle, 
as its name suggests, draws rectan- 
gles. Pass four coordinate values 
to locate the upper left and lower 
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Program in the fast lane with 
Borland’s new Turbo Pascal 4.0! 


ur new Turbo Pascal® 

4.0 is so fast, it’s 

almost reckless. How 
fast? Better than 27,000 lines 
of code per minute.* That’s 
more than twice as fast as 
Turbo Pascal 3.0. 


iow veRsion 


4.0 Technical Highlights: 


@ Compiles 27,000 lines per 
minute 

@ Includes automatic project Make 

@ Supports > 64K programs 


@ Uses units for separate 
maneen 4.0 breaks the code 
@ Integrated development barrier 


environment 
@ Interactive error detection/ 
location 
@ Includes a command line version 
of the compiler 
Highly compatible with 3.0 


No more swapping code in 
and out to beat the 64K code 
barrier. Designed for large 
programs, Turbo Pascal 4.0 
lets you use all 640K of 
memory in your computer. 


For the IBM PS/2™ and the IBM® and Compaq” fami- 
lies of personal computers and all 100% compatibles 


Sieve (25 iterations) 


Turbo Pascal 4.0 Turbo Pascal 3.0 
Size of Executable File 2224 bytes 11682 bytes 
Execution speed 9.3 seconds 9.7 seconds 


Sieve of Eratosthenes, run on an 8MHz IBM AT 


Since the source file above is too small to indicate a difference in compilation speed we compiled our CHESS program trom Turbo Gameworks to give you a 
(rue sense of how much faster 4.0 really is! 


Compilation of CHESS.PAS (5469 lines) 


Turbo Pascal 4.0 Turbo Pascal 3.0 
Compilation speed 12.1 seconds 35.5 seconds 
Lines per minute 27,119 9,243 


CHESS.PAS compiled on an 8 MHz IBM AT 


4.0 uses logical 
units for separate 
compilation 

Pascal 4.0 lets you break 
up the code gang into “units,” 
or “chunks.” These logical 
modules can be worked with 
swiftly and separately. 4.0 
also includes an automatic 
project Make. 


4.0’s cursor automat- 
ically lands on any 
trouble spot 

4.0’s interactive error 
detection and location means 
that the cursor automatically 
lands where the error is. 
While you’re compiling or 
running a program, you get 
an error message and the cere 
cursor flags the error’s Ss eaten 
location for you. 


Only $99.95 


60-Day Money-back Guarantee ** 


For the dealer nearest you, 
or to order now, 


Call (800) 543-7543 


“Run on an BMHz IBM AT 


“*It within 60 days of purchase this product does not perform in accor- 
dance with our claims, call our customer service department, and we will 
arrange a retund 

All Borland products are trademarks ot registered trademarks of Borland 
International, Inc. Copyright ©1987 Borland International, Inc. BI 1166A 


YES ’ I want to upgrade to Turbo Pascal 4.0 and the 4.0 Toolboxes 
e 


: .. Suggested Upgrade 
If you are a registered Turbo Pascal user and have not been notified of Please check box(es) Retail Price Serial No. 
Version 4.0 by mail, please call us at (800) 543-7543. To upgrade if 
you have not registered your product, just send the original registration pall ay rela i a $ 98.95 Merced 
feee | bey : O Turbo Pascal Tutor 69.95 19.95 
orm from your manual and payment with this completed coupon to: © Turbo Pascal Database Toolbox 99.95 29.95 
Turbo Pascal 4.0 Upgrade Dept., Borland International ; ab cin on sang _ a 
1 urbo Pascal itor |} 00iDOx R & 
4585 Scotts Valley Drive, Scotts Valley, CA 95066 © Turbo Pascal Numerical Methods Toolbox 99.95 29.95 
Name D Turbo Pascal Gameworks 99.95 29.95 ——= 
; Total product amount $= 
Ship Address CA and MA residents add sales tax es . 
City State In US please add $5 shipping and handling for each product 
Outside US please add $10 shipping & handling 
Zip _________ Telephone ( ) for each product C=. 
Total amount enclosed $ 


This offer is limited to one upgrade per valid registered product. It is good until June 30, 1988, Not 
good with any other offer from Borland. Outside U.S. make payments by bank draft payable in U.S. dol- 


Please specify diskette size 5M" 


D 3%" 


lars drawn on a U.S. bank. CODs and purchase orders will not be accepted by Borland. 


For the IBM PS/2™ and the IBM® and Compaq® families of personal computers and all 100% 
compatibles 


"To qualify for the upgrade price you must give the serial number of the equivalent product you are 
upgrading. 


Payment O VISA © MC QO Check O Bank Draft 
Credit card expiration dates = /_ 
Card # 
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PROCEDURE DoGraphics; 


VAR ch : Char; 
xmax, ymax : Integer; 
xrad, yrad : Integer; 
xX, ¥ : Integer; 
BEGIN 
xmax := GetMaxX + 1; 
ymax := GetMaxY + 1; 
xrad := xmax DIV 8; { X radius 
yrad := ymax DIV 8; { Y radius 
SetColor( White ); 
REPEAT 


x := Random( xmax ); 
y := Random( ymax ); 
Ellipse( x, 
Y, 
0, 
360, 
Random( xrad ), 
Random( yrad ) ); 


SetFillStyle¢ 1 + Random( 11 ), 


1 + Random( GetMaxColor 
FloodFill( x, y, White ) 
UNTIL Keypressed; 


ch := Readkey 
END; { DoGraphics } 


limit > 
limit } 


{ X coordinate value } 
{ Y coordinate value } 
{ Starting angle } 

{ Ending angle } 

{ X radius } 

{ Y radius } 


{ pattern } 
) Ds fcotor > 


{ Fill ellipse > 


Figure 6. Filled ellipse demonstration procedure replacing DoGraphics in 


Listing 1. 
CONSTANT 


EmptyFill 0 
SolidFill 1 
LineFill 2 
LtSlashFill 3 
SlashFill 4 
BkSlashFill 5 
LtBkSlashFill 6 
HatchFill 7 
XHatchFill 8 
InterleaveFill 9 
WideDotFill 10 
CloseDotFill 11 
UserFill 12 


Table 4. SetFillStyle patterns. 


MEET THE BGI 
continued from page 18 


right corners of a rectangular area 
on screen. To draw rectangles at 
random in the color passed to 
SetColor, change Line to 
Rectangle in Figure 3. 

But, you say, you want boxes 
filled with color, not just the out- 
lines that Rectangle gives? Okay, 
replace Rectangle with Bar. 
Notice that Bar does not fill the 
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FILL EFFECT 


Background color 
Solid color 

Lines (---) 

Thin slashes (///) 
Thick slashes (///) 
Thick backslashes (\\\) 
Thin backslashes (\\\) 
Light hatch marks 
Heavy hatch marks 
Interleaved lines 
Sparse dots 

Dense dots 

Previous SetFillPattern 


insides of boxes with the colors 
passed to SetColor. To specify a 
fill color for Bar, pass two word 
parameters—pattern and color— 
to SetFillStyle. 

Table 4 lists the constants you 
may assign to pattern in order to 
select different fill styles for Bar. 
As always, the color parameter is a 
value from 0 to GetMaxColor. 
The complete procedure for dis- 
playing filled boxes in a variety of 


| colors and patterns is in Figure 4, 


which replaces DoGraphics in 
Listing 1. 

Circles and ellipses. Three basic 
procedures draw curves in BGI 


graphics: Arc, Circle, and Ellipse. 
Arc draws a partial circle. Circle 
draws a complete circle. Ellipse 
draws an oval, which may or may 
not be circular. 

To experiment with Arc, replace 
DoGraphics in Listing 1 with Fig- 
ure 5. Arc takes five parameters to 
draw a semicircle. The first two 
values specify the (x,y) coordinate 
of the semicircle’s center of ra- 
dius. The next two values specify 
starting and ending angles, form- 
ing imaginary spokes joining the 
semicircle center with the two 
ends of the arc. Angles may have 
any values from 0 to 360; an angle 
with 0 degrees intersects the arc at 
3 o'clock, and greater angles move 
counterclockwise. The final Arc 
parameter specifies the semicir- 
cle’s radius (i.e., the distance of 
the drawn arc from its center). 

The Circle procedure is easier 
to use and takes only three 
parameters: x and y values that 
specify the circle’s center, and a 
radius value. To experiment with 
Circle, replace Arc (all five lines) 
in Figure 5 with: 


Circle( 

Random( xmax ), {X} 
Random( ymax ), {Y} 
Random( 50 ) ); {radius} 


Circle always draws a round cir- 
cle—not such an easy feat when 
you consider that pixels on most 
PC displays are not square or even 
close to it. Because of this, the ker- 
nel has to adjust the circle’s width 
and height according to the dis- 
play’s aspect ratio. Otherwise, cir- 
cles would be egg-shaped. BGI 
graphics makes drawing round 
circles easy—you don’t have to 
deal explicitly with the display’s 
aspect ratio. 

This advantage becomes more 
apparent when you use proce- 
dures like Ellipse. Unlike Circle, 
this procedure does not adjust for 
the screen’s aspect ratio. Ellipse 
takes six parameters: x and y 


coordinate values, starting and 
ending angles (like Arc), and two 
radii that represent invisible 
horizontal and vertical axes within 
the ellipse’s boundaries. To dis- 
play round circles with Ellipse, 
you have to adjust the axes your- 
self in order to compensate for 
the current display’s aspect ratio. 

Just for fun, let’s fill ellipses 
with patterns and colors, as we 
did earlier with rectangles using 
procedure Bar. Again, SetFillStyle 
selects a fill pattern and color. 
This time, however, there’s no 
filled-oval procedure similar to 
Bar. Instead, we need the proce- 
dure FloodFill, which fills en- 
closed shapes with the pattern 
and color passed to SetFillStyle. 
The complete FloodFill proce- 
dure, which replaces DoGraphics 
in Listing 1, is in Figure 6. 

Figure 6 demonstrates how to 
fill shapes with FloodFill. The 
shape must be completely 
enclosed with pixels of a single 
color that is different from the 
background color. Any gaps in the 
shape’s outline allow the fill color 
to leak outside of the shape, like 
paint through a sieve. Figure 6 
prevents this disaster by calling 
SetColor with the constant White, 
which is the color that Ellipse 
uses for the drawn figure’s border. 

Notice that the starting and 
ending angles in Ellipse are 0 and 
360. These are the correct values 
to use when drawing ellipses with 
no gaps in the border. If you want 
to draw a semiellipse—like a semi- 
circle, but not necessarily round— 
use values in the range of 0 to 
360, as you did with Arc. 

The two radii values, limited to 
0..xrad-1 and 0..yrad-1 in Figure 
6, control the width and height 
of the ellipse. Before the 
REPEAT..UNTIL loop, xrad and 
yrad are limited to one-eighth the 
display width and height. Thus, 
ovals appear in relatively equal 
sizes in all display resolutions. 

I can’t stress enough the impor- 
tance of writing graphics pro- 
grams in this way to ensure that 

continued on page 22 


Default Font test pattern ABCDEFG 12345 


Default Font test pattern 


Default Fon 


Press Enter to continue... 


Figure 7. A BGI bit-mapped font in increasing sizes. Note how aliasing (the 
stairstep effect on diagonal character segments) becomes more objectionable as the 
characters are enlarged. 


A A AY BAY LA 


ah 
Press Enter to continue... 


Figure 8. A BGI stroked font in increasing sizes. Stroked fonts often improve in 
appearance as they are enlarged. Note the clipping of drawn characters at the 
bottom edge of the screen. 


May/June 1988 TURBO TECHNIX 21 


LISTING 1: RANDOMGR.PAS 


PROGRAM RandomGraphics; 


(* Demonstrates BGI graphics--Turbo Pascal 4.0--by Tom Swan *) 


USES Crt, Graph; 

VAR grDriver, grMode, grError : Integer; 
PROCEDURE DoGraphics; 

VAR : Char; 


BEGIN 
REPEAT 
SetColor( 1 + Random( GetMaxColor ) ); 
LineTo( Random( GetMaxX + 1 ), 
Random( GetMaxY + 1 ) ); 
UNTIL Keypressed; 
ch := Readkey 
END; { DoGraphics } 


BEGIN 

grDriver := Detect; 
InitGraph( grDriver, grMode, '' ); 
grError := GraphResult; 
IF grError <> GrOk 
THEN Writeln( ‘Graphics error : 
ELSE BEGIN 

DoGraphics; 

CloseGraph 

END 


LISTING 2: FONTDEMO.PAS 


PROGRAM FontDemo; 


{ Select color } 


{ x coordinate value } 
{ y coordinate value } 


', GraphErrorMsg( grError ) ) 


(* Demonstrates BGI text fonts--Turbo Pascal 4.0--by Tom Swan *) 


USES Crt, Graph; 


VAR grDriver, grMode, grError : Integer; 


{ Display message, wait for Enter key, clear screen. } 


PROCEDURE Pause; 


BEGIN 
GotoxY( 2, 23 ); 
Write( ' Press Enter to continue...' ); 
Read|n; 
ClearViewPort 
END; { Pause } 


{ Display test text for font number fn } 
PROCEDURE TestFont( fn : Integer ); 


VAR size : Integer; { Font size } 


name : String([10]; { Font name } 
BEGIN 
CASE fn OF 
DefaultFont : name 
TriplexFont =: name 
Small Font : name 
SansSerifFont : 
GothicFont 
END; € case } 


'Default'; 
'Triplex'; 
'Small'; 
'Sans Serif'; 
‘Gothic! 
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they run correctly in different dis- 
play modes. Never use fixed con- 
stants for coordinate limits in your 
programs; instead, call GetMaxX, 
GetMaxY, and GetMaxColor early 
in your program and then assign 
their return values to variables. 
Later in your program, use the 
values in those variables to adjust 
other variables accordingly so that 
the graphics conform to the size 
and color palette of the current 
graphics mode. 

The final steps in Figure 6 call 
SetFillStyle to select a fill pattern 
and color at random; FloodFill 
then paints the oval. FloodFill’s x 
and y parameters locate a pixel 
somewhere inside the border of 
the shape to be filled. The third 
parameter, White in this example, 
specifies the shape’s border color. 


INTERMISSION 


So far, we’ve covered initialization 
techniques, pixels, lines, rectan- 
gles, filled bars, arcs, circles, 
ellipses, and flood filling. These 
are merely the fundamentals of 
BGI graphics, which has many 
more routines for drawing poly- 
gons (filled and unfilled), moving 
the CP, customizing fill and line 
patterns, adjusting line widths, 
drawing pie chart wedges, display- 
ing 3-D bars like those in a fancy 
bar chart, playing around with 
color palettes, inspecting the dis- 
play’s aspect ratio, using bit-map 
images, animating with multiple 
display pages, and more. 

Let me take a moment to go 
over a few special routines that 
you'll undoubtedly use from time 
to time. 


Clearing the screen. To clear the 
display call ClearDevice, which is 
faster than ClearViewport. (Clear 
the display with ClearViewport 


only if you call SetViewPort to re- 
strict the viewport—the visible 


window in which the drawing FOR size := 1708 DO 

appears— to be less than the full BEGIN 

screen width and height.) To SetColor( size ); 

change the background color SetTextStyle( fn, HorizDir, size ); 

need by both: ClearDevice and MoveTo( 0, GetY + TextHeight('M') + 2 ); 2 
OutText( name + ' Font test pattern ABCDEFG 123456 !a#S%"' ) 

ClearViewPort, call SetBkColor END { for } 

with a value from 0 to 

GetMaxColor. END; { TestFont } 

Moving and inspecting CP. PROCEDURE WritelnTest; { Display text via Writeln } 

MoveTo moves CP to any (x,y) 


coordinate. This step is useful BEGIN 


; ] GotoxY( 2, 2); 

when you're preparing - pi Writeln¢ ' This text is displayed by Writeln' ); 
commands such as Line, which Palise 

starts drawing at CP. MoveRel END; { WritelnTest > 


moves CP relative to the current 
position of CP, according to the 

amounts specified by the integer 
parameters DX and DY. Use nega- | | var fontNumber : Integer; 
tive DX values to move CP to the ch : Char; 

left, and positive values to move it 


PROCEDURE DoGraphics; { Display graphics } 


to the right. Negative DY values oO on ee ee ee ee ee a A 
move CP up, and positive values ae aca pal aan tele Awol Sigeol Tg allan 
move it down. Integer functions { Draw blue border and restrict viewport to protect 
GetX and GetY return the CP’s border from erasure: } 
current x and y values. SetColor( Blue ); 
R Lantt si SetViewP Rectangle¢ 0, 0, GetMaxX, GetMaxY ); 

estricted views. SetViewr ort SetViewPort( 1, 1, GetMaxX-1, GetMaxY-1, ClipOn ); 
takes five parameters. As in WritelnTest; { Demonstrate Writeln in graphics mode } 
Rectangle, the first four values FOR fontNumber := DefaultFont TO GothicFont DO 


BEGIN 
TestFont( fontNumber ); 
Pause 


represent the two coordinates that 
depict the upper left and lower 
right corners of a rectangle. 
SetViewPort restricts future draw- 


ing to the area within this rectan- END { for } 
gle’s borders only if the fifth END; { DoGraphics } 
parameter, which is Clipping of 
type Boolean, equals True. If Re 
ae is : : grDriver := Detect; 
Clipping is False, then the kernel InitGraph( grDriver, grMode, '' ); 
allows drawing to occur outside of grError := GraphResult; 
the viewport boundaries. This IF grError <> GrOk _ 
technique is useful for centering Lies real ‘Graphics error : ', GraphErrorMsg( grError ) ) 
the coordinate origin (i.e., (0,0)), DoGraphics; 
which is normally located in the CloseGraph 
upper left corner of the screen. END 


This advanced technique won't 
be detailed here, but it shows 


why you might want to turn 
Clipping off. LISTING 3: COLORS.PAS 


continued on page 24 
PROGRAM Colors; 


(* Displays Color Chart--Turbo Pascal 4.0--by Tom Swan *) 


USES Crt, Graph; 


VAR grDriver : Integer; Graphics driver number } 
grMode_ =: Integer; Graphics driver mode } 
grError : Integer; Graphics error code } 


barWidth : Word; Pixel width of bars } 
labelHeight : Word; Pixel height of bar labels } 
bwd2 : Word; barWidth DIV 2 } 

bwt2 : Word; barWidth times 2 } 

thd2 : Word; labelHeight DIV 2 } 
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{ Initialize global variables, load text font, and display title. 
PROCEDURE Initialize; 


BEGIN 

{ Select text style, direction, size, and justification. 
Then, display title at top center of screen. Reduce text 
size for displaying labels under bars: } 
SetTextStyle( SansSerifFont, HorizDir, 5 ); € Title } 
SetTextJustify( CenterText, CenterText ); 
MoveTo( GetMaxX DIV 2, GetMaxY DIV 8 ); 
OutText( 'Color Numbers' ); 
SetTextStyle( SansSerifFont, HorizDir, 4 ); € Labels } 


Initialize a few global variables: } 
barWidth := ( ( GetMaxX + 1 ) DIV ( GetMaxColor + 1 ) ) DIV 2; 
labelHeight := 2 * TextHeight( 'O' ); 
thd2 := labelHeight DIV 2; { labelHeight DIV 2 } 
bwd2 := barWidth DIV 2; { barWidth DIV 2 } 
bwt2 := barWidth * 2 { barWidth times 2 } 
END; { Initialize } 


{ Draw a single bar filled with a color } 
PROCEDURE DrawOneBar( x1, y1, x2, y2 : Integer; color : Word ); 


BEGIN 
SetFillStyle( SlashFill, color ); 
Bar( x1, y1, x2, y2 ); 
SetColor( White ); 
Rectangle( x1, y1, x2, y2 ) 
END; { DrawOneBar } 


{ Select pattern, color } 
{ Draw filled bar } 

{ Outline bars in white } 
{ Draw outline } 


{ Display color number centered at (x,y) under bar } 
PROCEDURE LabelBar( x, y : Integer; color : Word ); 
VAR s : String(2]; { Color number as a string } 
BEGIN 
Str¢ color, s ): 
OutTextXY( x, y, S$ ) 
END; { LabelBar } 


Convert color to string s } 
Display text at (x,y) } 


PROCEDURE DrawBars; ({ Draw color bars and wait for key press } 


Coordinate values } 
FOR-loop variable } 
Keyboard character } 


VAR x1, yl, y2 : Integer; 
color : Word; 
ch : Char; 


BEGIN 
x1 := bwd2; Initialize starting x1 value } 
y1 := GetMaxY DIV 3; Initialize y1 to top of bar } 
y2 := GetMaxY - labelHeight; { Initialize y2 to bottom of bar } 
FOR color := 0 TO GetMaxColor DO 


BEGIN 
DrawOneBar( x1, y1, x1 + barWidth, y2, color ); 
LabelBar( x1 + bwd2, y2 + lhd2, color ); 
x1 s= x1 + bwt2 { Move x1 right for the next bar } 
END; { while } 
ch := ReadKey { Wait for keypress } 
END; { DrawBars } 
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Switching from text to graphics. 
Occasionally, you'll want to switch 
from a graphics screen to a text 
screen and then back again. You 
could call CloseGraph to shut 
down the BGI kernel, and then 
call InitGraph to reinitialize it 
again, but there’s an easier way. 
Call RestoreCrtMode to tempo- 
rarily return to the display mode 
that was active prior to calling 
InitGraph. When you're finished 
with the previous display mode, 
return to your graphics mode by 
calling SetGraphMode and 
passing it the grMode variable 
returned by InitGraph. 


CLASSY CHARACTERS 


Fonts. Earlier, I promised to 
explain more about fonts. The 
BGI supports two kinds of fonts: 
bit-mapped and stroked. Charac- 
ters in bit-mapped fonts are com- 
posed of rectangular pixel arrays. 
Characters in stroked fonts are 
composed of vectors—line seg- 
ments whose sizes and directions 
are defined as relative to some 
starting point. 

The difference between the two 
kinds of fonts is important when 
changing the default size of char- 
acter images. Blowing up bit- 
mapped fonts is done by simply 
enlarging the pixels. This makes 
the characters look blocky, with 
huge stair steps (this effect is 
called aliasing) on their sloping 
parts (see Figure 7). Stroked fonts 
are enlarged by making their com- 
ponent line segments longer, so 
aliasing does not occur. Because 
stroked fonts are defined as col- 
lections of line segments rather 
than pixel blocks, characters look 
good (in many cases, better) when 
enlarged (see Figure 8). Bit- 
mapped fonts do offer one ad- 
vantage—speed. Stroked-font 
characters, with their many line 
segments, take longer to draw 
than do bit-mapped characters. 


The BGI kernel currently sup- 
ports one bit-mapped font and 
four stroked fonts (see Table 2). 
For comparison, Listing 2 displays 
short text lines in all possible 
fonts. To run the program, you 
need to place the .CHR files listed 
in Table 2 into the same directory 
that you specified with the string 
parameter to InitGraph. 


Making your selection. Procedure 
TestFont in Listing 2 shows the 
correct way to select a font and 
size. After the CASE statement sets 
string variable name to the font’s 
name, a FOR loop cycles integer 
variable size from 1 to 8. Most 
fonts look best with small sizes in 
this range, but you have to experi- 
ment. Different fonts with the 
same size values appear larger or 
smaller than others. 

Use SetTextStyle to select a 
font, direction, and size. The first 
parameter in SetTextStyle is the 
font number, which is one of the 
five constants DefaultFont, 
TriplexFont, SmallFont, Sans- 
SerifFont, and GothicFont. 
DefaultFont (0) is a bit-mapped 
font. The other four fonts are 
stroked. 

The second SetTextStyle 
parameter can be either HorizDir 
or VertDir. Use HorizDir to dis- 
play text horizontally from left to 
right, and use VertDir to display 
text vertically from top to bottom. 
The final SetTextStyle parameter 
specifies the font size. 

SetTextStyle loads the appro- 
priate .CHR font file from disk, 
searching the pathname passed to 
InitGraph. If the kernel can’t find 
this font file, SetTextStyle returns 
an error code through Graph- 
Result. (Note that for brevity’s 
sake, Listing 2 does not check for 
this error.) 


Displaying text. OutText and 
OutTextXY display text in the 
current font, direction, and size, 
using the color most recently 
passed to SetColor. OutText takes 
a single string parameter and dis- 
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BEGIN 
grDriver := Detect; 
InitGraph( grDriver, grMode, '' ); 
grError := GraphResult; 
IF grError <> GrOk 
THEN 
Writeln( 'Graphics error : ', GraphErrorMsg( grError ) ) 
ELSE 
BEGIN 
Initialize; { Perform various initializations } 
DrawBars; { Display color bars } 
CloseGraph { Restore former text mode } 
END 


LISTING 4: KALEIDO.PAS 


PROGRAM Kaleidoscope; 
(* Displays Kaleidoscope Patterns--Turbo Pascal 4.0--by Tom Swan *) 


USES Crt, Graph; 


VAR grDriver : Integer; { Graphics driver number } 
grMode =: Integer; { Graphics driver mode } 
grError : Integer; { Graphics error code } 


PROCEDURE DoGraphics; { Display graphics until a key is pressed } 


VAR xmax, ymax : Integer; { Maximum x, y values } 
x1, y1, x2, y2 : Integer; { Line endings } 
dx1, dy1, dx2, dy2 : Integer; { Change in x1,y1,x2,y2 } 
displayPeriod : Word; { Time between clearing } 
LinePeriod : Word; { Time each pattern lives } 
ch : Char; { For clearing keypress } 


PROCEDURE Initialize; { Perform various initializations } 


BEGIN 
Randomize; { "Seed" new random sequence } 
displayPeriod := 0; { Force call to NewisplayPeriod } 
xmax := GetMaxX DIV 2; { Set x and y maximums to middle } 
ymax := GetMaxY DIV 2; { of display resolution } 


Restrict viewport to 1/4 entire display. With clipping 
off, this centers the origin (0,0) and makes mirror 
images in the four quadrants easy to draw. } 


SetViewPort( xmax, ymax, GetMaxX, GetMaxY, ClipOff ) 
END; { Initialize } 


{ Clear screen and initialize displayPeriod, 
controlling length of time between screen clears: } 
PROCEDURE NewDisplayPeriod; 


BEGIN 
ClearDevice; { Clear entire display } 
displayPeriod := 6 + Random( 24) { 6..29 } 
END; { NewDisplayPeriod } 


{ Select coordinates, movements, linePeriod, 
and line color at random: } 
PROCEDURE NewValues; 
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Random( xMax : { x1 <- 0..xmax 
Random( yMax . { y1 <- 0..ymax 
Random( xMax { x2 <- O..xmax 
Random( yMax { y2 <- 0..ymax 
Random( 16 ) { dx1 <- -8..+7 
Random( 16 ) { dyl <- -8..+7 
Random( 16 ) € dx2 <- -8..+7 
Random( 16 ) - 8; € dys <- -8..47, 
LinePeriod := 5 + Random(120); { linePeriod <- 5..124 } 
SetColor( 1 + Random( GetMaxColor ) ) 
END; { NewValues } 


ae ee ee ee ee oe oe oe 
nnununh uw uw 
www WwW www 


{ Adjust line coordinates, making lines appear to move: } 
PROCEDURE MoveCoordinates; 


BEGIN 

x1 := x1 + dx1; { Add appropriate "delta," } 
= yl + dy; { meaning "change in," value } 
= x2 + dx2; { to line end coordinates. } 
= y2 + dy2 


y1 
x2 
y2 


END; { MoveCoordinates } 


PROCEDURE DrawLines; { Draw Lines mirrored in four quadrants } 


BEGIN 
Line( -x1, “x2, { upper left quadrant } 
Line( -x1, -x2, { lower left quadrant } 
Linec x1, x2, { upper right quadrant } 
Line¢ x1, x2, { lower right quadrant } 
END; { DrawLines } 


BEGIN 
Initialize; 
REPEAT 
IF displayPeriod <= 0 
THEN NewDisplayPeriod; { Clear screen } 
NewValues; 
WHILE ( linePeriod > 0 ) AND ( NOT Keypressed ) DO 
BEGIN 
Delay( 5 ); 
MoveCoordinates; 
DrawLines; 
linePeriod := linePeriod - 1 
END; { while } 
displayPeriod := displayPeriod - 1 
UNTIL Keypressed; 
ch := Readkey 
END; { DoGraphics } 


{ Set the speed limit } 
{ Animate display } 
{ Draw mirror images } 


BEGIN 
grDriver := Detect; 
InitGraph( grDriver, grMode, '' ); 
grError := GraphResult; 
IF grError <> GrOk 
THEN 
Writeln( ‘Graphics error : ', GraphErrorMsg( grError ) ) 
ELSE 
BEGIN 
DoGraphics; 
CloseGraph 
END 


MEET THE BGI 
continued from page 25 


plays its characters beginning at 
CP. After OutText, CP moves to 
the position just after the last 
display character. OutTextXY 
ignores CP and takes x and y in- 
teger parameters, plus the string 
to be displayed. 

Listing 2 calls MoveTo, initial- 
izing CP to a starting position 
before calling OutText. Each new 
text line must be positioned a little 
further down the screen, because 
the characters are larger on each 
successive line. Therefore, to cal- 
culate the position of each new 
text line, the function TextHeight 
is called from MoveTo’s parame- 
ter line. TextHeight returns the 
pixel height of a string; in this 
case, the string consists of the 
letter M. (M was chosen here 
because it is about as tall as any 
character gets.) The sum of the 
current y coordinate value (GetY) 
added to the value returned by 
TextHeight, plus two additional 
pixels for spacing, yields the new y 
coordinate for the next text line. 

Notice that when it calls 
OutText, string variable name is 
concatenated to the quoted string 
literal “Font test pattern 
ABCDEFG 123456 !@#$%"’” 
using the string concatenation 
operator +. Remember, OutText 
and OutTextXY take a single 
string parameter. Unlike Write 
and Writeln, you can’t separate 
multiple parameters to OutText 
and OutTextXY with commas. 
Also, in order to display integer 
and real number values, you must 
first use Turbo Pascal’s Str proce- 
dure to convert such values to 
strings, and then pass the equiva- 
lent string values to OutText or 
OutTextXY. 


Using Write and Writeln in 
graphics mode. You can also mix 
text and graphics with Write and 
Writeln, but you can display BGI 
fonts only with OutText and 
OutTextXY. In graphics mode, 
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Write and Writeln always use the 
same system-resident font that 
they use when called from text 
mode. If your program uses the 
Crt unit, which links fast, direct 
video routines to Write and 
Writeln, you must set the Boolean 
variable DirectVideo to False. 

If you don’t do this, Write and 
Writeln won't work on graphics 
screens. If your program does not 
use Crt, then Write and Writeln 
work normally. 


BGI ROUNDUP 


I'll leave you with two programs 
that use many of the routines 
covered in this article. The pro- 
grams, Listings 3 and 4, are heavi- 
ly commented and you should be 
able to explore them without any 
further help. 


dise 


Listing 3, which displays a color 
chart, adjusts for all possible dis- 
play resolutions and color sets. As 
I suggested earlier, strive for this 
same flexibility in your own pro- 
grams, so that your software runs 
correctly in a wide variety of PC 
graphics modes. Why limit your 
audience? 

Listing 4 displays an animated 
color kaleidoscope that, again, 
works in all modes supported by 
BGI graphics. The program uses 
the technique (mentioned earlier) 
of setting a viewport without 
enabling viewport clipping in 
order to center the origin. This 
technique divides the display into 
four quadrants, making the mirror 
images easier to draw than they 
would be if the origin was in the 
top left corner. The program is 
great for parties and such—you 
can drag it out when somebody 
asks, “So what does this computer 
of yours do?” 

By now, you should have a feel- 
ing for the depth of BGI graphics 
capabilities, even though we’ve 
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Program 


only scratched the surface. Of all 
the graphics systems I’ve used in 
various languages, there’s no 
question that the BGI kernel is a 
top-notch performer. If you’re 
interested in graphics program- 
ming on the PC, you no longer 
have to eye those pretty Amigas 
and Ataris down at the budget 
computer store. You may discover 
that the new BGI frontier, and a 
copy of Turbo Pascal or Turbo C, 
are all you need. @ 


Tom Swan is the author of Master- 
ing Turbo Pascal 4.0, 2nd Edition, 
Howard W. Sams, 1988; Mastering 
Turbo Pascal Files, Howard W. 
Sams, 1987; and Programming 
With Macintosh Turbo Pascal, 


John Wiley & Sons, 1987. 


Listings may be downloaded from 
CompuServe as PASBGI.ARC. 
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TURBO PASCAL 


PLOTTING THE MANDELBROT 
SET WITH THE BGI 


Meet the most complex object in mathematics — the 
Mandelbrot Set—brought to you in living color by the 


Borland Graphics Interface. 


Fred Robinson 


Back in the fall of 1985, I sat poring over 
the latest Scientific American, dumbfound- 
ed. Professor Dewdney’s Computer 
Recreations article—the cover story, no 
less—unveiled the Mandelbrot Set, one of 
the most beautiful and probably the most 
complex creature ever to emerge from the realm of 
mathematics. 

Well, if you have seen the October, 1985, Scientific 
American, you've probably also been bitten by the 
Mandelbrot bug. My own experience may be typical. 
I’ve implemented software to generate the Set on the 
Apple II+, and later in several different languages 
on the PC, culminating with Turbo Pascal 3.0 and the 
Turbo Pascal Graphix Toolbox. Now the next step 
has arrived—Turbo Pascal 4.0 and the Borland 
Graphics Interface team up to provide the 
Mandelbrot Set generator presented here. 


A COMPLEX NOTION 


First, let’s take a brief look at some concepts that 
are key to describing the Mandelbrot set: complex 
numbers, imaginary numbers, and the complex 
number plane. 


PROGRAMMER 


Complex and imaginary numbers. A complex number 
contains some form of the square root of -1, which 
by convention is called 7. Unlike the square roots of 
positive numbers, i and multiples of i cannot be 
found on the real number line. For this reason, mul- 
tiples of 7 are called imaginary numbers (hence the use 
of the 2). 7 isn’t normally used in everyday calcu- 
lations. 

A complex number has two parts: a real number 
part, which is some value along the real number 
line; and an imaginary number part. For example, 
the sum of 9.7 + 3.57 is a complex number. Complex 
numbers can be added to, subtracted from, multi- 
plied with, and divided by other complex numbers. 
(These operations are not as easy to perform on 
complex numbers as they are on ordinary numbers, 
but they can be done.) 
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Complex numbers also have size. The size of a 
complex number is its distance from the origin, (0,0); 
this distance is calculated by using the Pythagorean 
Theorem. For example, the size of 9.7 + 3.57 is Sqrt 
(9.7? + 3.5”), or Sqrt (31.65), or about 10.31213. 


The complex number plane. The complex number 
plane is represented by a Cartesian coordinate system 
whose X axis is labeled the real axis, and whose Y 
axis is labeled the imaginary axis. In this system, all 
ordinary real numbers fall on the X axis. Any given 
point on the plane corresponds to a complex num- 
ber. For example, the point (9.7, 3.5) corresponds to 
the complex number 9.7 + 3.51. 


WHAT IS THE MANDELBROT SET? 


The Mandelbrot Set is a region of the complex num- 
ber plane, situated between -2 + -2i and 2 + 2i, that 
contains a set of complex numbers. When these 
numbers are repeatedly subjected to a certain for- 
mula, they never achieve a size greater than 2. Natu- 
rally, a plane contains just as many points that will 
exceed 2 as it does points that will not exceed 2. The 
interesting part comes near the border between the 
two regions. 

The formula that is used to determine which num- 
bers belong to the Mandelbrot Set is deceptively sim- 
ple: Initialize z to the complex point c in question, 
and simply repeat the following equation until either 
the size of z exceeds 2, or else the process has been 
repeated an arbitrary number of times: 

2 = 2~ = 

Once the size of z exceeds 2, it never returns to less 
than 2. Some numbers take quite a while to reach 
this size, other numbers never do, and still others 
pass 2 almost immediately. For our purposes (given 
somewhat slow general-purpose computers), the 


maximum number of iterations can be cut to 
about 250. 


Figure 1. The full Mandelbrot Set, plotted from -2.0 to 2.0 and -2.0i to 2.0i. 
Other views are obtained by choosing a subset of the image and recalculating it 
so that the new image occupies the entire image area. 


Figure 2. Deep in the heart of the Set, 
highlighting the fractal nature of the 
edge of the Set. The perimeter of the Set 
is infinitely long, even though the Set’s 
area is finite. 


THE FRACTAL EDGE 


What is the point of all this? Well, 
the Mandelbrot Set has an edge 
that is fractal in nature. By specify- 
ing a small portion of the complex 
number plane, mapping it onto a 
PC display screen, and suitably 
increasing the iteration limit, you 
can see details of the fractal edge 
in ever-decreasing size. Zooming 
in even closer, the tiny details in a 
larger picture can be seen to con- 
tain even smaller details. 

I could go on like this for quite 
a while, but the Set speaks for it- 
self. Figures 1 and 2 give you 
some idea of what to expect from 
a plot of the Set on an EGA in 
640 X 350 graphics mode. Figure 
1 is a view of the entire Set from a 
height. The ranges used to gener- 
ate Figure 1 are -2.0 to 2.0 and - 
2.0i to 2.07. Zooming down several 


continued on page 30 
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input real and imaginary ranges 
input iteration maximum 


for c.i = low_imaginary to high_imaginary 
for c.r = low_real to high_real 
z=c 
repeat 


22 22 hc 
until size (z)>2 or too many iterations 
if size (z)>2 then 

plot Ce.r, ¢.1) 


Figure 3. This algorithm determines if a point on the complex number plane 
belongs to the Mandelbrot Set. 


Write Better 


Turbo 4.0 Programs... 
Or Your Money Back 


You'll write better Turbo Pascal 4.0 programs easier and faster 
using the powerful analytical tools of Turbo Analyst 4.0. 
You get * Pascal Formatter * Cross Referencer * Program 
Indexer * Program Lister * Execution Profiler, 
and more. Includes complete source code. 

Turbo Analyst 4.0 is the successor to the 
acclaimed TurboPower Utilities: 


“Tf you own Turbo Pascal you should own the Turbo 
Power Programmers Utilities, that’s all there is to it.” 
Bruce Webster, BYTE Magazine, Feb. 1986 


Turbo Analyst 4.0 is only $75. 


A Library of Essential Routines 
Turbo Professional 4.0 is a library of more than 400 state-of-the-art 
routines optimized for Turbo Pascal 4.0. It includes complete 
source code, comprehensive documentation, and demo 
, programs that are powerful and useful. Includes 
_// * TSR management * Menu, window, and data 
=|) entry routines * BCD « Large arrays, and more. 


Turbo Professional 4.0 is only $99. 
Call toll-free for credit card orders. 


1-800-538-8157 ext. 830 (1-800-672-3470 ext. 830 in CA) 


Satisfaction guaranteed or your money back within 30 days. 


TABS 


TurboPower Software 
P. O. Box 66747 
Scotts Valley, CA 95066-0747 


Fast Response Series: 

= T-DebugPLUS 4.0—Symbolic 
run-time debugger for Turbo 4.0, 
only $45. ($90 with source code) 

@ Overlay Manager 4.0—Use over- 
lays and chain in Turbo 4.0, only $45. 
Call for upgrade information. 


Turbo Pascal 4.0 is required. 

Owners of TurboPower Utilities w/o 
source may upgrade for $40, w/source, 
$25. Include your serial number. For 
other information call 408-438-8608. 
Shipping & taxes prepaid in US. & 
Canada. Elsewhere add $12 per item. 


MANDELBROT SET 
continued from page 29 


levels into the Set revealed the 
image shown in Figure 2. 

The first step in generating the 
Mandelbrot Set is to master com- 
plex arithmetic. Complex addition 
and subtraction are trivial, but 
complex multiplication is not so 
easy. Remember how to multiply 
polynomial expressions? FOIL: 
First + Outside + Inside + Last. 
There is enough similarity be- 
tween a complex number and a 
polynomial for this technique to 
work. Multiplying two numbers, 
A+ Bi and C + Di, yields: 

AC + ADi + BCi + BDii 
This equation is simplified to: 
(AC + -BD) + (AD + BC)i 

Remember, since 7 is the square 
root of -1, i X 7 yields -1, produc- 
ing a negative BD in the result 
shown above. Multiplying the A's, 
Bs, Cs, and Ds and then summing 
the results generates a new com- 
plex number. 

Once that process is under- 
stood, generation of the Set is 
straightforward. The basic algo- 
rithm, which steps across a region 
one pixel at a time, is shown in 
Figure 3. 


PLOT POINTERS 


For the best results, assign a color 
to each point plotted based upon 
the number of iterations neces- 
sary to determine whether the 
point belongs to the Set. Points 


\)| belonging to the Set are usually 
| left black. Points outside of the 


Set can be plotted many ways; the 
easiest way is to illuminate those 
points that require an even num- 
ber of iterations. This approach is 
adequate for a two-color display, 
such as the display supported 

by the Turbo Pascal Graphix 
Toolbox. 

It’s also possible to write a Set 
generator using the Borland 
Graphics Interface and Turbo 
Pascal 4.0. This method results in 
smaller code and faster compila- 
tion, as well as portability to differ- 
ent display devices, including 
color displays. The use of color 
offers more possibilities. For 


continued on page 32 
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LISTING 1: MANDEL4.PAS 


PROGRAM Mandel 4; END (* CASE *}; 


{This program generates a section of the Mandelbrot Set, can save it 


on disk, and use existing Mandelbrot pictures to zoom further into InitGraph (Device, Graph_Mode, TP_Path); 
the Set.) 
CASE Device OF 
USES CGA, MCGA, RESERVED, 
Crt, Graph, Cmplx; { CMPLX.TPU is created from CMPLX.PAS } ATT400: BEGIN 
Color_Count := 54; 

CONST Use_Color := Colors_4; 
Scan_Width = 359; € 719 (max Hercules) DIV 2 } Max_Colors := 3; 
Max_Scan_Lines = 349; { PC3270 maximum > Max_X := GetMaxX 
Aspect = 0.75; { Typical screen aspect ratio } END <* CASE CGACO, MCGACO, ATT4O0CO *}; 
Real_Length = 30; 

Yes_N_No: SET OF char = ['Y', ‘N°, ‘y®, ‘n']; EGA, VGA, 

Yes: SET OF char = ['Y', 'y']; EGA64: BEGIN 

No: SET OF char = ['N', 'n']; Color_Count := 56; 

TP_Path = 'T:'; Use_Color := Colors_16; 
Max_Colors := 15; 

TYPE Max_X := GetMaxX DIV 2 
Scan_Line = ARRAY [0..Scan_Width] OF byte; END {* CASE EGAHi, VGAHi, EGA64Lo *}; 
Scan_Line_Ptr = ~“Scan_Line; 

Real_String = STRING(Real_Length]; ELSE BEGIN 
Color_Array = ARRAY [(0..55] OF integer; Color_Count := 56; 
Use_ Color := Colors_2; 
CONST Max_Colors := 1; 


Max_X := GetMaxX DIV 2 
END {* CASE ELSE *} 
END {* CASE *}; 


Colors_2: 


{ Color arrangement for 

{ 2-color screens 

FOR X := 0 TO Max_Scan_Lines DO 
New (Screen(X]); 


eceocooco°o 


RestoreCrtMode 
END {* Initialize *}; 


Colors_4: 


{ Color arrangement for (RRR ERE RRR ERR RRR RRRERERERRARRERREREREREERREEERERRERRERE HY) 


{ 4-color screens 


WenNnwe 


PROCEDURE Plot (X, Y: integer; 


Colors_16: Color: word); 
{ This procedure plots points on the screen. For high-resolution- 


{ Color arrangement for }> width screens, two adjacent pixels are set. } 


{ 16-color screens > 


BEGIN 
CASE Device OF 
CGA, MCGA, RESERVED, 
ATT4OO: PutPixel (X, Y, Color); 


Ch: Char; 
Pert ELSE BEGIN 
Low, High, Delta: Complex; PutPixel (X*2, Y, Color); 
Dots_Horizontal, Dots_Vertical, Start_Y, Max_Count, Color_Count, PutPixel (Xx*2+1, Y, Color) 
Device, Graph_Mode, Max_Colors, Max_X: integer; END (* CASE ELSE *} 
Use Color: Color_Array; END {* CASE *} 
Picture_Loaded: boolean; END {* Plot *}; 
File Name: STRING(80); : 
r ‘ (ARARRRRRRRRAAREAARERR ERE RREEREREREERARRERERRERRREREREEEER EERE EER) 
Data_Line: Scan_Line; 
Screen_File: FILE OF Scan_Line; PROCEDURE Define Screen; 
Screen: ARRAY [0..Max_Scan_Lines] OF Scan_Line_Ptr; - ! 
Screen_Data: RECORD d {This procedure defines the area of the Mandelbrot Set to be viewed. 
tants cae Start: integer; It can either be typed in at the keyboard, loaded as a partially 
= ’ LL ' . 
ich Real. Wigh tne? Real Senin: completed screen, or as a smaller sector of a completed picture. } 
Note: String(200) VAR 
END ABSOLUTE Data_Line; xX, Y: integer; 


Temp, Ratio: double; 


(REI IIIT RII II IIR III III IIIT II III ISI IIS IASI SSS SSSAI SAAS SISSSSASIS, 


 Galalahalahaledalehelehaleleleialeleieieloleleleielelodeieiaieloieteteleletaietotoietaiatoleiaiateloleinisieieieieieieisisiaioio? 
PROCEDURE Initialize; 
PROCEDURE No_Blank (VAR RS: Real_String); 


{ This procedure checks for the graphics screen and selects a mode 
based on a compromise between resolution and the number of colors. } 


{ This procedure removes leading blanks from the string RS. } 


VAR 


X: integer; BEGIN 


WHILE RS(1]=' ' DO 
RS := Copy (RS, 2, Length (RS)-1) 


BEGIN END {* No_Blank *); 


TextMode (LastMode); 
Teas (i, peed . {PERRRRARARERAERERERERERRAREREREREREERRRERERER EE ERRREEEEERARERERE 
ound ; 
DirectVideo := False; 
File Name := ''; 
Picture_Loaded := False; : P 
DetectGraph (Device, Graph_Mode); { This procedure allows the user to select a sub-section of a 


X := GraphResult; completed screen to be blown up, effectively zooming in on a 
smaller area. 


PROCEDURE Sub Picture; 


IF X<>grOk THEN . * 
BEGIN Pressing keys 2 thru 5 changes the grid on the screen. A sub- 


Writeln ('Sorry, I can''t cope with this: ', GraphErrorMsg (X)); section may be chosen by pressing a letter, starting with A in the 
Halt upper left corner and moving across: 


a wily SyRNEA 
| me EEE 


CASE Device OF 
EGA: - 
va Pet] 

MCGA: | s | 

EGA64: Graph _Mode := listi : r 

ATT400: Graph_Mode := ATT4O0CO; isting continue 7 

PC3270: Graph Mode := PC3270Hi; g on page 33 

HercMono: Graph_Mode := HercMonoHi; 

CGA, RESERVED: Graph _Mode := CGACO 
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MANDELBROT SET 
continued from page 30 


instance, the CGA medium-resolu- 
tion mode gives you three colors 
to use if you reserve black for the 
Set. More advanced display 
boards, of course, provide more 
colors. My own system, which now 
uses a Genoa Spectrum, generates 
16 colors at 320 X 200. This is a 
good compromise between resolu- 
tion, image quality, and speed of 
generation. 

Another point: Since every pixel 
on the screen requires a certain 
amount of real-number calcula- 
tion to determine the pixel’s color, 
a math coprocessor is essential. 
Performing the calculations with- 
out a coprocessor takes about four 
times longer than performing 
them with a coprocessor. Also, 
keep in mind that all black points 
that represent the Set itself re- 
quire the full number of iterations 
in order to calculate. Thus, images 
that contain a great deal of black 
take longer to calculate than those 
with less black. 

Finally, when you look at very 
small regions near the edge of the 
Set, it’s necessary to increase the 
number of iterations in order to 
reveal details that would otherwise 
be set to the black color of the Set. 
Near the edge of the Set, the num- 
ber of iterations that is required 
to attain a size greater than 2 in- 
creases dramatically. This increase 
results in longer image generation 
times. 


MANDEL4 


Mandel4 (Listing 1) takes advan- 
tage of many display types, using 
the new standard BGI functions to 
detect and initialize the displays. It 
accepts starting regions from the 
keyboard, or else takes a smaller 
region from a completed screen. 
Mandel4 requires the code in 
CMPLX.PAS (Listing 2), which 
is a unit that contains several 
complex-number math routines. 
In terms of resolution and 
color, ’'ve made some compro- 
mises when dealing with certain 
screens. The horizontal resolution 
of displays that contain a great 
number of pixels in the horizontal 
dimension has been halved. This 
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allows faster picture creation with 
the loss of only a small amount of 
visual information. In screens 
with few colors, the colors are 
grouped together to make the 
smaller details of the Set more vis- 
ible on the screen (the alternative 
is a polychromatic hash where the 
iteration count changes drastically 
from one pixel to the next). 

Another compromise is the 
method used to store the pictures. 
Rather than encoding several pix- 
els into a byte, each pixel is stored 
in a full byte. This increases 
speed, and allows up to 256 pos- 
sible colors for a pixel (this color 
range is supported by MCGA 
and VGA displays). This storage 
method, however, creates rather 
large picture files, so be careful 
that you have enough room avail- 
able on your disk when saving an 
image as a file. 

Mandel4 gives you the oppor- 
tunity to either load a previously 
created image (by typing the name 
of a picture file), or to generate a 
totally new image (by typing in the 
real and imaginary ranges, along 
with the maximum iteration 
count). The program also allows 
entry of a note for later reference. 
Once this information is entered, 
Mandel4 plots the area encom- 
passed by the ranges specified. 

If you load a partially finished 
picture, Mandel4 continues to 
work on it. If the picture you load 
is complete, however, it’s thrown 
onto the screen and a grid ap- 
pears that divides the screen into 
quarters. By pressing keys 2 
through 5, you can change the 
grid to another grid in the range 
of 2 X 2 through 5 X 5. Each 
smaller area has the same propor- 
tions as the picture on the screen. 
An area can be chosen by press- 
ing a letter key, starting with A in 
the upper left corner and moving 
across to the right, as shown in 
Figure 4. 

While Mandel4 is working on 
a picture, a dot moves across the 
screen and marks the pixel that is 
currently being calculated. When 
the picture is done, or if you 
press a key during the drawing, 
Mandel4 gives you an opportunity 
to save the image in a file, and 
then asks if you want to generate 
another image. You can either 
start over from scratch, or else use 


of 


After pressing 2: 


After pressing 5: 


Figure 4. How the screen is divided 
after image plotting. To choose a sub- 
section of the image to “zoom,” simply 


press the letter that corresponds to the 


desired subsection. 


the picture you've just completed 
as a starting point for the next 
image. 

Mandel4 plots to many different 
displays, but picture files plotted 
on one display can’t be moved to 
another (such as from CGA to 
EGA). 


GET SET 

I guess it’s possible to go over- 
board with the Mandelbrot Set, 
but I think that that’s the most fun 
of all, don’t you? Try it and you'll 
see. @ 


Fred Robinson is a computer pro- 


grammer in the research department of 


Ross Roy, Inc., an advertising firm in 
Michigan. 


Listings can be downloaded from 
CompuServe as MANDEL.ARC. 
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RestoreCrtMode; 
Write 
(‘Maximum iteration count = ', Max_Count, '. Change it? (Y/N) 


REPEAT 
Ch := ReadKey 
UNTIL Ch IN Yes_N_No; 


Writeln (Ch); 


IF Ch IN Yes THEN 
BEGIN 
Once a section has been chosen, the program proceeds to calculate REPEAT , : 
and display the smaller section, as large as the screen may allow.) Write ('Enter maximum iteration count: '); 
{$I-} Readin (Max_Count) ($I+} 
CONST UNTIL IOResul t=0; 
Max_Letter: ARRAY [2..5] OF char = ('D', "I", "Pt, 'Y¥'); 
IF Max_Count<10 THEN 
VAR Max_Count := 10; 
Ch: char; 
New_Size, Size, X, Y, Z, Sector, Sector_X, Sector_Y: integer; Screen_Data.Count := Max_Count 
END {* THEN *}; 
BEGIN 
Size := 1; Write ('Enter note: '); 
File Name := ''; Readln (Screen_Data.Note); 
Ch := ‘2's SetGraphMode (Graph_Mode) 
END {* Sub Picture *}; 
REPEAT 
IF Ch IN ct2'..'5") THEN (PARRA RARER EERE RRR IERIE IIR REE IIIA AIR IIIA IAS, 
BEGIN {* Change grid *} 
New_Size := Ord (Ch) - Ord ('0'); BEGIN {* Define_Screen *} 
Ch sw Nt; 
IF Size<>New_Size THEN 
BEGIN IF Picture_Loaded THEN 
{ Undo existing grid } BEGIN 
FOR X := 0 TO Dots_Horizontal DO Write ('Use picture in memory? (Y/N) '); 
FOR Z := 1 TO Size-1 DO 
BEGIN REPEAT 
Y := 2 * Dots Vertical DIV Size; Ch := ReadKey 
Plot (X, Y, Screen[Y] ~ (X]) UNTIL Ch IN Yes_N_No; 
END {* FOR, FOR *)}; 
Writeln (Ch) 
FOR Y := 0 TO Dots_Vertical DO END (* THEN *}; 
FOR Z := 1 TO Size-1 DO 
BEGIN Ch IN No THEN 
X := Z * Dots_Horizontal DIV Size; BEGIN 
Plot (xX, Y, Screen[Y] ~[X]) Write ('Load a picture file? (Y/N) '); 
END {* FOR, FOR *}; 
REPEAT 
Size := New Size; Ch := ReadKey 
UNTIL Ch IN Yes_N_No; 
{ Make new grid > 
FOR X := 0 TO Dots Horizontal DO Writeln (Ch); 
FOR Z := 1 TO Size-1 DO 
BEGIN Ch IN Yes THEN 
Y := Z * Dots Vertical DIV Size; BEGIN € Load picture file } 
Plot (X, Y, Max_Colors-Screen[Y) *[X]) REPEAT 
EWD (* FOR, FOR *); Write (‘Enter name of file: '); 
Readin (File_Name); 
Y: TO Dots Vertical Do Assign (Screen_File, File Name); 
FOR Z := 1 TO Size-1 DO {$I-} Reset (Screen_File) ($I+); 
UNTIL 1O0Resul t=0; 


FOR 


X := Z * Dots_Horizontal DIV Size; A - 
Plot (X, Y, Max_Colors-Screen[Y] * [X]) Read (Screen_File, Data_Line); 
END {* FOR, FOR * 
Ew c* THEN *) : FOR X := 0 TO Screen Data.Start-1 D0 
END {(* THEN *)}; Read (Screen_File, Screen[X] ~); 


Ch := UpCase (ReadKey) Close (Screen_File); 
UNTIL (Size IN [2..5]) AND (Ch IN ['A'..Max_Letter[Size]]); Picture_Loaded := True 
a END {* THEN *} 
{ Calculate new limits > ELSE 
«= * TAly: 
Pade ap died pete tatls a BEGIN { Get info from keyboard } 
Sector_Y := Size - 1 - Sector DIV Size; REPEAT . i 
Sub_Comp (High, Low, Delta); Write (‘Enter range for the real (horiz.) axis: 
Div_C_By_R (Delta, Size, Delta); {$1-) Readin (Low.R, High.R) (SI+) 
Low.R := Low.R + Delta.R * Sector_X; UNTIL (1OResult=0) AND (Low.R<>High.R); 
High.R := Low.R + Delta.R; z 
Low.I := Low.I + Delta.I * Sector_Y; IF Low.R>High.R THEN 
High.I := Low. + Delta.I; BEGIN 
Temp := Low.R; 
WITH Screen_Data DO Low.R := High.R; 
BEGIN High.R := Temp 
Start_Y := 0; END {* THEN *}; 
Dots_H := Dots_Horizontal; 
Dots_V := Dots Vertical; REPEAT 
Count := Max_Count; Write ('Enter range for the imaginary (vert.) axis: 
Str (Low.R, Low Real); {$I-} Readln (Low.I, High.I) {($I1+} 
Str (Low.I, Low_Imag); UNTIL (1OResult=0) AND (Low.1<>High.1); 
Str (High.R, High Real); 
Str (High.I, High_Imag); IF Low.I>High.I THEN 
No_Blank (Low_Imag); BEGIN 
No_Blank (Low_Real); Temp := Low.1; 
No_Blank (High_Imag); Low.I := High.I; 
No_Blank (High _Real) High.I := Temp 
END (* WITH *)}; END {* THEN *); 


REPEAT 
Write ('Enter maximum iteration count: 
{$I-} Readin (Max_Count) ($I+} 

UNTIL IOResult=0; 
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IF Max_Count<10 THEN 
Max_Count := 10; 


Write ('Enter note: '); 
Readin (Screen_Data.Note); 
Start_Y := 0; 

Sub_Comp (High, Low, Delta); 
Ratio := Delta.I / Delta.R; 
SetGraphMode (Graph_Mode); 


IF Ratio>=Aspect THEN 
BEGIN 
Dots_ Horizontal := Round ((Max_X + 1) * Aspect / Ratio) - 1; 
Dots Vertical := GetMaxY 
END (* THEN *) 


ELSE 

BEGIN 

Dots_Vertical := Round ((GetMaxY + 1) * Ratio / Aspect) - 1; 

Dots_Horizontal := Max_X 

END (* ELSE *); 

WITH Screen_Data DO 

BEGIN 
Dots_H := Dots_Horizontal; 
Dots_V := Dots_Vertical; 
Count := Max_Count; 
Str (Low.I, Low_Imag); 
Str (Low.R, Low_Real); 
Str (High.I, High_Imag); 
Str (High.R, High_Real); 
No_Blank (Low_Imag); 
No_Blank (Low Real); 
Wo Blank (High_Imag); 
No_Blank (High_Real) 
END (* WITH *); 


Picture_Loaded := False; 
File_Name := '' 
END (* ELSE *} 

END {* THEN *); 


Picture_Loaded THEN 
BEGIN { Dump picture onto the screen } 
SetGraphMode (Graph_Mode); 


WITH Screen_Data DO 
BEGIN 
Start_Y := Start; 
Max_Count := Count; 
Dots_ Horizontal := Dots_H; 
Dots_Vertical := Dots_V; 
Val (Low_Real, Low.R, X); 
Val (Low_Imag, Low.I, X); 
Val (High_Real, High.R, X); 
Val (High_Imag, High.I, X) 
END {* WITH *); 


FOR Y := 0 TO Start_Y-1 DO 
FOR X := 0 TO Dots_Horizontal DO 
Plot (X, Y, Screen[Y] “(X]); 


IF Start_Y>GetMaxY THEN 

Sub_Picture { Get a subregion of the completed picture } 
ELSE 

Sub_Comp (High, Low, Delta) € Continue drawing the picture } 
END {* THEN *}; 


Delta.R := Delta.R / (Dots_Horizontal + 1); 


Delta.! := Delta.I / (Dots_Vertical + 1) 
END (* Define_Screen *); 


{(AHRRRRR RRR ARR ARERR AA RRAR AER ERRE ARERR ERE RRRERRERERRRER RARER EER) 


PROCEDURE Generate; 


{ This is where most of the program's time is spent, generating the 
screen. The section marked 1* is where code has been optimized by 
putting the complex-number math instructions in this procedure rather 
than calling the actual procedures. } 


VAR 
xX, Y, Count: integer; 
Z_Point, C_Point: Complex; 
Temp: double; 


BEGIN {* Generate *} 

Plot (Dots_Horizontal, Dots Vertical, Max_Colors); 
C_Point.I := High.I - Start_Y * Delta.1; 

Y := Start_y; 


WHILE (Y<=Dots_Vertical) AND NOT KeyPressed DO 
BEGIN 
FillChar (Screen[Y]~, Scan_Width+1, 0); 
C_Point.R := Low.R - Delta.R; 


FOR X := 0 TO Dots_Horizontal DO 
BEGIN 
Plot (X, Y, Max_Colors); 
C_Point.R := C_Point.R + Delta.R; 
Z_Point := C_Point; 
Count := 0; 
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WHILE (Count<=Max_Count) AND (Square Size_Of_C (Z_Point)<4.0) DO 
BEGIN 
Mult_Comp (Z_Point, Z_Point, Z_Point); > 
Add_Comp (Z_Point, C_Point, Z_Point); }> 


Temp := Sqr (Z_Point.R) - Sqr (Z_Point.1) + C_Point.R; 
Z_Point.I := 2.0 * Z_Point.I * Z_Point.R + C_Point.1; 
Z_Point.R := Temp; 

Count := Succ (Count) 

END {* WHILE *}; 


IF Count<Max_Count THEN 
Screen[Y] “(X] := Use_Color [Count MOD Color_Count]; 


Plot (X, Y, Screen(Y]~ (X]) 
END {* FOR *}; 


C_Point.I := C_Point.I - Delta.1; 
bE oe 
END {* WHILE *}; 


Screen_Data.Start := Y 
END {* Generate *); 


{PRRRRRRARRRERRRRRRERRER RRR RRRERERERRERERERR ERE RE RRR REBEERERER EERE 


PROCEDURE Wrap_Up; 
{ This procedure deals with the shutting down of a picture. } 


VAR 
X: integer; 


BEGIN 
Picture_Loaded := True; 


IF KeyPressed THEN 
Sound (440) 


ELSE 
BEGIN 
Sound (660); 
Delay (20); 
Sound (1000) 
END (* ELSE *}; 


Delay (50); 
NoSound; 


Ch := ReadKey; 


RestoreCrtMode; 
Write ('Save picture? (Y/N) '); 


REPEAT 
Ch := ReadKey 
UNTIL Ch IN Yes_N_No; 


Writeln (Ch); 


IF Ch IN Yes THEN 
BEGIN 
IF File_Name<>'' THEN 
BEGIN 
Write ('Save as ', File_Name, '? (Y/N) 


REPEAT 
Ch := ReacKey 
UNTIL Ch IN Yes_N_No; 


Writeln (Ch) 
END {* THEN *) 


ELSE 
Ch := 'N'; 


IF Ch IN No THEN 
BEGIN 
Write (‘Enter filename to save it in: '); 
Readin (File_Name) 
END {* THEN *); 


Assign (Screen_File, File_Name); 
Rewrite (Screen_File); 
Write (Screen_File, Data_Line); 


FOR X := 0 TO Screen_Data.Start-1 DO 
Write (Screen_File, Screen(X]~); 


Close (Screen_File) 
END (* THEN *); 


Write ('Do another? (Y/N) '); 


REPEAT 
Ch := ReadKey 
UNTIL Ch IN Yes_N_No; 


Writeln (Ch) 
END {* Wrap Up *}; 


{PRRRARAAA AAR RR AAA R EERE ARR RARER ERR AREER EEARER RRR RERERERARR RE) 


BEGIN (* main *} 
Initialize; 


REPEAT 
Define_Screen; 
Generate; 
Wrap_Up 

UNTIL Ch IN No 

END. 


LISTING 2: CMPLX.PAS 


UNIT Cmplx; 


{ In the following descriptions, 
Capital letters (A, 8) are real numbers or real parts of complex 
numbers. Lowercase letters (a, b) are real factors of complex 
parts. i is the square root of -1 (/-1). 


CONTENTS: Add_Comp (C1, C2, C_Out); 
Sub_Comp (C1, C2, C_Out); 
Mul t_Comp (C1, C2, C_Out); 
Mul t_RC (C, R, C_Out); 
Sub_C_From_R (R, C, C_Out); 
Div_c By.R (C, R, C_Out); 
Size_Of_C (C); 
Square_Size_Of_C (C); 


INTERFACE 


TYPE 
Complex = RECORD 
R, I: double 
END; 


PROCEDURE Add_Comp (A, B: Complex; 
VAR C: Complex); 


PROCEDURE Sub_Comp (A, B: Complex; 
VAR C: Complex); 


PROCEDURE Mult_Comp (A, B: Complex; 
VAR C: Complex); 


PROCEDURE Div_Comp (A, B: Complex; 
VAR C: Complex); 


PROCEDURE Div_R_By_C (R: double; 
C: Complex; 
VAR C_Out: Complex); 


PROCEDURE Mult_RC (C: Complex; 
R: double; 
VAR C_Out: Complex); 


PROCEDURE Sub_C_From_R (R: double; 
C: Complex; 
VAR C_Out: Complex); 


PROCEDURE Div_C_By_R (C: Complex; 
R: double; 
VAR C_Out: Complex); 


FUNCTION Size_Of_C (C: Complex): double; 
FUNCTION Square_Size_Of_C (C: Complex): double; 


(COI IAI I IORI IOI ITI IRI IORI IIT IIA IISA III IIIA III SSS IIISISI SSIS, 
IMPLEMENTATION 


PROCEDURE Add_Comp (A, B: Complex; 
VAR C: Complex); 


{ RESULT == (Atai)+(B+bi) == Atai+B+bi == (A+B)+(atb)i > 


{(ARRRARARRREARRRAAARAAR RARER ARREAR RARER AER EREREEERERARERERE ER EERE D) 


PROCEDURE Sub_Comp (A, B: Complex; 
VAR C: Complex); 


{ RESULT == (Atai)-(B+bi) == Atai-B-bi == (A-B)+(a-b)i > 


END (* Sub_C 


{ARRRAARARARRARAR AREER AR AAR RARER ARREREARRERERERERERERERE REAR EES) 


PROCEDURE Mult_Comp (A, B: Complex; 
VAR C: Complex); 


{ RESULT == (A+ai)(B+bi) == AB + Abi + Bai + aibi == 
(AB-ab)+(Ab+aB)i > 


+ 
* 


A 
A. 
; 


END c Mult _Comp > 


{(ARRRRRARRERRRRRRRAER RARER EER ERERERRERREREEEREERERERERREERER RRR ANY, 


PROCEDURE Div_Comp (A, B: Complex; 
VAR C: Complex); 


{ RESULT == (Atai)/(B+bi) == (AB+ab)/(B*+b?)+((aB-Ab)/(B*+b?))i > 


VAR 
D: double; 


BEGIN 

D := Sqr (B.R) + Sqr (B.1); 

«R := (AR * BR + A.I * BI 
= (A.1 * B.R - ALR * B.1 

END {* Div_Comp *}; 


»/D 
»/D 


{(ARRRRRARARRAARRRERERER RARER ARR AER ARR ERE RREREERREREREERRER REREAD) 


PROCEDURE Div_R_By_C (R: double; 
C: Complex; 
VAR C_Out: Complex); 
VAR 
A: Complex; 
BEGIN 
A.R z= R; 
A.1 := 0; 
Div_Comp (A, C, C_Out) 
END (* Div_R_By_C *}; 


{PRRRRRRRARRRARAR REAR RR ARR ER RARER AREER ERE RERERERIERIER EERE RARER REN ) 


PROCEDURE Mult_RC (C: Complex; 
R: double; 
VAR C_Out: Complex); 


{ RESULT == (C+ci)R == CR+cRI > 


{®RRRARRRAARRARAARRRRRRRRRARARRRRER ARERR EERE RERERE EER EERER EARS ARES) 


PROCEDURE Sub_C_From_R (R: double; 

C: Complex; 

VAR C_Out: Complex); 
{ RESULT == R-(Ctci) == R-C-ci == (R-C)-ci } 
BEGIN 
C_Out.R z= R - C.R; 
C_Out.I := -C.I 
END (* Sub_C_From_R *); 


{ARAARAANAAAARAAARAREARERERERARERAREEAERERARERENRERRRELR RARER ERE AD 


PROCEDURE Div_C_By_R (C: Complex; 
R: double; 
VAR C_Out: Complex); 


{ RESULT == (C+ci)/R == C/B+ci/R == (C/R)+(c/R)i > 


R 

ae By. Rs 
{PRARRARERARERARRRRRRERE ER REREREEREREREEREREREEEERERERERERER AREER, 
FUNCTION Size_Of_C (C: Complex): double; 
{ RESULT == J(C?¥#c?) > 
BEGIN 
Size_Of_C := Sqrt (Sqr (C.R) + Sqr (C.1)) 
END {* Size_Of_C *}; 
(ARRRRAARRRAARAAAARRRERERRREREREERARERREREERERERERRREREREEREER EEE) 
FUNCTION Square_Size_Of_C (C: Complex): double; 
{ RESULT == C? +c? )} 
BEGIN 
Square_Size_Of_C := Sqr (C.R) + Sqr (C.I) 
END {* Square_Size_Of_C *); 
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TURBO PASCAL 


USING UNITS TO HIDE DATA 
STRUCTURE DETAILS 


Hiding data structure details is more than just keeping 


secrets —it can make everyone’s work easier. 


Marshall Brain 


There is more to Turbo Pascal’s new units 
feature than separate compilation. In 
“Getting to Know Units” (TURBO TECH- 
NIX, November/December, 1987), Tom 
Swan explained how units may be used to 
—_s. divide a large program into smaller, more 
maintainable modules. This is certainly units’ major 
role in Turbo Pascal programming, but like packages 
in ADA and modules in Modula-2, units also play a 
role in facilitating portable coding, and in limiting 
the use of intermodule “sneak paths” and other 
undesirable programming habits. 


SQUARE ONE 


UNIT STRUCTURE 


Let’s recap unit structure briefly. Every unit has two 
parts: an interface section and an implementation 
section. 

The interface section of the unit contains declara- 
tions of constants, types, and variables, as well as the 
definitions of “public” subprograms and their pa- 
rameters. These subprograms and declarations are 
globally “visible” to any program using the unit. For 
example: 


UNIT MyUnit; 
INTERFACE 


VAR 
A,B,C: INTEGER; 


PROCEDURE P(VAR I: INTEGER); 


In any program that uses unit MyUnit, the variables 
A, B, and C will be global variables, and procedure P 
will be a public procedure. 

The implementation section of a unit comes after 
the interface section, and is “invisible” to programs 
that use the unit. The implementation section may 
contain its own “private” constants, variables and 
types, but a program that uses the unit cannot access 
them. This also applies to the actual bodies of the 
procedures declared in the interface section. These 
bodies are part of the implementation section, and 
are also invisible to programs that use the unit. 


The interface section of a unit gives a program 
access to the objects and capabilities inside of the 
unit. The implementation section allows the pro- 
grammer to hide data structures and all code used 
to manipulate those structures. 


JUST ENOUGH KNOWLEDGE 


When a team of several programmers develops large 
programs, this dual structure of units forces a kind of 
modularity that is very different from that obtained 
by cutting monolithic programs up into libraries of 
procedures. The structure of units allows each pro- 
grammer to be assigned a complete, standalone por- 
tion of the larger program that can be compiled and 
tested on its own. The programming team is forced 
to define and resolve the interfaces among all 
modules before programming can begin. The inter- 
face sections of the units can actually be written as 
part of the program spec, long before programming 
begins in earnest. When it comes time to integrate 
the units together into the complete program, this 
upfront work on the module interfaces pays off by 
making the integration and subsequent program 
verification happen much more quickly and 
smoothly. 

The invisibility of each unit’s implementation sec- 
tion gives units another important advantage. The 
implementation section can be used to hide details 
that cloud a program’s structure, or to hide code that 
may need to be changed in the future. Programmers 
who are not responsible for writing the unit itself are 
given just enough knowledge to use the unit’s facili- 
ties in their own work, but not enough knowledge to 
allow them to make unwarranted assumptions about 
the internals of program modules written by others. 
“The IntervalTimer procedure keeps its seconds 
count in a word variable internally for speed,” a pro- 
grammer might think, “so I can use a word variable 
to hold intervals and not worry about overflow, even 
though the interface is a LongInt.” Units would keep 
that programmer from making that mistake by hid- 
ing the way IntervalTimer keeps house internally. 
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Units also allow complex, con- 
fusing code to be packaged in a 
form that is much easier to use. 
The confusing details are hidden 
within the unit, while any pro- 
gram using the unit accesses the 
code through a relatively small 
number of easy-to-understand 
procedure and function calls. 


MAKING USE OF 
INVISIBILITY 


The true function of any high- 
level language is the artful hiding 
of program details. Consider one 
simple Turbo Pascal statement: 


New (Node); 


Here, the program creates a 
variable on the heap, which is 
pointed to by a pointer named 
Node. The process behind this 
statement involves identifying the 
type to which Node points, deter- 
mining the size of Node’s refer- 
ent, traversing the free list to find 
a block of free memory large 
enough to contain the referent, 
modifying the free list to indicate 
that another chunk of heap 
memory has been allocated and 
used, and finally loading the ad- 
dress of the allocated space into 
the pointer variable Node. Since 
all of that complication is hidden 
behind one small statement, the 
programmer can concentrate 
instead on what to do with Node 
and its dynamic referent on the 
heap. 

Similarly, hiding certain things 
in the implementation section of 
one or more units makes con- 
struction of the main program 
much easier, and also makes code 
changes completely transparent to 
all programs that use the unit. 

This technique is especially 
powerful when applied to data 
structures. Consider this scenario: 
You have written a large and com- 
plex data management program 
for your company that is based on 
a very large linked list of data. 
Many programs written for in- 
house use revolve completely 
around a single large data struc- 
ture in this manner. 

As people in your company 
become dependent on this pro- 

continued on page 38 


LISTING 1: LIST.PAS 


unit addr_list; 


{Unit to hide a linked list data structure from the main 
program. } 


{Marshall Brain Box 37224 Raleigh, NC 27597 ver 1.0 9/13/87} 
INTERFACE 
{This portion of the unit is used to describe the type of 
objects used by the unit and the operations available to 
manipulate those objects. This section is visible to any 
program using this unit.} 


TYPE 
name_string=STRING([10]; 
Addr=RECORD 

last_name, first_name:name_string; 
street:STRING[40]; 
city:STRING(10]; 
state:STRING(2]; 
zip:STRING[10]; 
phone: STRING[15]; 
comment : STRING [40]; 
END; 


PROCEDURE load_file(filename:STRING; VAR error:Boolean); 
{LOAD_FILE attempts to load the data structure from 
the filename specified. If unsuccessful, ERROR will 
be true. File is assumed to be in sorted order.} 


PROCEDURE create_file(filename:STRING); 
{creates a new file of name FILENAME.} 


PROCEDURE save_file; 
{SAVE_FILE saves the data structure back to the file it 
was loaded from.} 


PROCEDURE find_first(lname, fname:name_string; VAR rec:Addr; 
no_match:Boolean); 
{FIND_FIRST will find the first record with a name that 
matches LNAME,FNAME. If a match is found, REC will contain 
the record found. Otherwise, NO MATCH will be true and REC 
will contain garbage.} 


PROCEDURE find_next(lname, fname:name_string; VAR rec:Addr; 
no_match:Boolean); 
{FIND_NEXT will find the next record matching LNAME, FNAME. 
It is assumed that FIND_FIRST was used first. NO_MATCH 
is set if there are no matches.) 


PROCEDURE add_rec(rec:Addr; VAR error:Boolean); 
{ADD_REC will add REC to the data structure, maintaining 
that data structure in sorted order by name. If the data 
structure is full, ERROR will be set true.} 


PROCEDURE delete_rec; 
{deletes the last record found using one of the FIND rtns.} 


PROCEDURE change_rec(rec:Addr); 
{replaces the last record found using one of the find rtns 
with rec. First and last name should not be changed, as this 
will destroy the linked list order. If the name needs 
to change, use DELETE_REC and ADD_REC instead.} 


FUNCTION size:word; 
{SIZE will contain the number of records in the data 
structure.} 


FUNCTION full:Boolean; 
{FULL will be false if space remains in the data structure.} 
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IMPLEMENTATION 
{This portion of the unit is invisible to the program, and 
can be used to hide that data structure.} 


{The data structure is currently implemented as a linked list.} 
TYPE 
pntr="ll_rec; 
Ul_rec=RECORD 
a:Addr; 
next,prev:pntr; 
END; 
VAR 
first, last,curr:pntr; 
f:FILE of Addr; 
found:Boolean; 


PROCEDURE init; 
{A hidden routine used to init variables.} 
BEGIN 
first:=NIL; 
last:=NIL; 
curr:=NIL; 
found:=False; 
END; 


PROCEDURE load_file{filename:STRING; VAR error:Boolean}; 
{LOAD_FILE attempts to load the data structure from 
the filename specified. If unsuccessful, ERROR will 
be true. File is assumed to be in sorted order.} 
VAR temp:Addr; p:pntr; err:Boolean; 
BEGIN 
init; 
{make sure that file exists.) 
Assign(f, filename); 
{$i-} Reset(f); {$it+} 
IF 1OResult=0 THEN 
BEGIN 
WHILE NOT EOF(f) DO 
BEGIN 
{append new records to the end of the linked list.} 
Read(f, temp); 
New(p); 
{init p> 
p°.a:=temp; 
p’.next:=NIL; 
p’.prev:=last; 
{create the links.) 
IF (first=NIL) THEN 
first:=p 
ELSE 
last” .next:=p; 
last:=p; 
END; 
Close(f); 
END 
ELSE 
error:=True; 
END; 


PROCEDURE create_file{filename:STRING); 
{creates a new file of name FILENAME.) 
BEGIN 
Assign(f, filename); 
init; 
END; 
PROCEDURE save_file; 


{SAVE_FILE saves the data structure back to the file it 
was loaded from.} 
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UNITS 
continued from page 37 


gram, they begin to demand more 
speed. (And as more data is con- 
tinually added to the list, the 
speed, of course, slows down.) 
After examining your program, 
you decide that the best way to 
speed it up is to abandon the 
linked list structure and switch to 
an efficient B-tree data structure. 
Unfortunately, literally thousands 
of references to the linked list are 
scattered throughout your pro- 
gram. It would take a great deal of 
time to find and change all those 
references, and the process would 
probably spawn any number of 
bugs in the code, all of which 
would have to be eliminated. 

Units can prevent situations like 
this by completely hiding the na- 
ture and details of the data struc- 
ture from the main program. To 
use units in this way, design a 
procedural interface to your data 
structure (in other words, make no 
direct references to the structure 
itself anywhere in the program) 
and define this set of routines in 
the interface section of a unit. For 
a data management unit, you 
might decide that the following 
routines are needed: create__file, 
load__file, save__file, add__rec, 
delete__rec, change__rec, 
find __first, find__next, size, and 
full. With these routines and a 
data record format in mind, you 
can write the interface section of 
your unit. 

Once the interface to the unit is 
designed, you can completely hide 
your implementation of the data 
structure in the implementation 
section of the unit. An example 
unit, using a linked list data struc- 
ture implementation, is shown in 
Listing 1, LIST.PAS. This unit im- 
plements the data management 
routines listed at the end of the 
previous paragraph. In the List 
unit, the design of the data struc- 
ture is completely invisible to the 
main program. Only the data 
record type, Addr, and the head- 
ers of the routines needed to 
manipulate the data structure are 
visible to users of the unit. Note 
the critical fact in reading the 
interface section of List: It speci- 
fies what each routine in the unit 
does without indicating how. 


THE BENEFITS OF 
STRUCTURE SECRECY 


When you separate a program 
from the data structure in this 
way, you gain four advantages: 


1. The program that uses the unit 
is conceptually easier to under- 
stand, because you now access 
the data structure solely 
through a set of high-level 
commands. The absence of 
more complex low-level data 
structure manipulation code 
makes your program much 
cleaner. 

2. The data structure can be com- 
pletely rebuilt at any time. You 
might start with an array be- 
cause it’s simple and fast for 
small quantities of data, then 
move to a linked list for its 
larger data space, and switch 
later to a B-tree for its faster 
access time with large data- 
bases. The main program ney- 
er changes at all, even though 
the structure containing its data 
changes dramatically through 
several revisions. 

3. If you ever need these same 
capabilities and data structure 
in another program (which is 
likely), you can easily reuse 
your unit with only minor mod- 
ifications to the data record 
declaration. 

4. The use of specific interface 
routines makes the data struc- 
ture much more reliable. Once 
the interface routines have 
been thoroughly debugged, it’s 
impossible to corrupt the data 
structure through the main pro- 
gram. This debugged code can 
then be used over and over 
again. 

Units can hide the details of 
any kind of data structure you 
wish to use. For example, a stack 
unit can be created using PUSH, 
POP, and CLEAR as the stack 
interface routines. The stack itself 
can be implemented using an 
array, a linked list, a file, or what- 
ever is appropriate, and the main 
program remains oblivious to im- 
plementation details. The same 
technique can be applied to 
queues, ring buffers, and so forth. 

Porting programs between 
hardware environments is 
another instance where hiding 


continued on page 40 


VAR p:pntr; 
BEGIN 
Rewrite(f); 
p:=first; 
{loop to end of linked list.} 
WHILE (p<>NIL) DO 
BEGIN 
{some 1/0 checking could be added.} 
Write(f,p°.a); 
{dispose of LL as it is saved.} 
first:=first”.next; 
dispose(p); 
p:=first; 
END; 
init; 
Close(f); 
END; 


PROCEDURE find(lname, fname:name_string; VAR rec:Addr; 
VAR no_match:Boolean); 
{This hidden routine loops through the LL looking for the 
name passed. } 
VAR stop:Boolean; 
BEGIN 
stop:=False; 
no_match:=True; 
{loop until end of list, match found, or past where name 
should be.} 
WHILE (curr<>NIL) AND no_match AND NOT stop DO 
BEGIN 
IF (lname>curr”.a.last_name) THEN {check next rec.} 
curr:=curr” .next 
ELSE IF (lname=curr”.a.last_name) THEN 
{check for first name match.} 
BEGIN 
IF (fname>curr”.a.first_name) THEN {check next rec.} 
curr:=curr” .next 
ELSE IF (fname=curr”.a.first_name) THEN {match found.} 
BEGIN 
rec:=curr’.a; 
no_match:=False; 
END 
ELSE {beyond where name can be.} 
stop:=True; 
END 
ELSE {beyond where name can be.} 
stop:=True; 
END; 
END; 


PROCEDURE find_first{lname, fname:name_string; VAR rec:Addr; 
no_match:Boolean}; 

{FIND_FIRST will find the first record with a name that 
matches LNAME,FNAME. If a match is found, REC will contain 
the record found. Otherwise, NO_MATCH will be true and REC 
will contain garbage.} 

BEGIN 

curr:=first; 

find(lname, fname, rec,no_match); 

found:=NOT no_match; 

END; 


PROCEDURE find_next{lname, fname:name_string; VAR rec:Addr; 
no_match:Boolean}; 
{FIND_NEXT will find the next record matching LNAME, FNAME. 
It is assumed that FIND_FIRST was used first. NO_MATCH 
is set if there are no matches.) 
BEGIN 
curr:=curr” .next; 
find(lname, fname, rec,no_match); 
found:=NOT no_match; 
END; 
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UNITS 


continued from page 39 
PROCEDURE add_rec{rec:Addr; VAR error:Boolean}; 
{ADD_REC will add REC to the data structure, maintaining data structure implementation 
that data structure in sorted order by name. If the data P 


structure is full, ERROR will be set true.} details can be critical. For exam- 


VAR temp:Addr; no_match:Boolean; p:pntr; ple, many mainframe programs 
BEGIN use large arrays (such as 500 X 
{check for heap overflow.} 500 element two-dimensional 
es pada i ti daca ak integer arrays) that are literally 
(find where new rec should go.) too large to fit into one of the PC’s 
curr:=first; 64K memory segments. Such a 
find(rec. last_name, rec. first_name, temp,no_match); program can usually be moved to 
ony new nee and tink 1 In.3 a PC—memory for the code is 
p. a:=rec; available in most cases. But to 
p’-next:=curr; allow the program to operate, the 
IF curr=NIL THEN p*.prev:=last ELSE p*.prev:=curr’.prev; array has to be broken down into 
IF curr=first THEN first:=p some other form, such as a linked 
ELSE IF Ccurr=NIL) THEN lest” .nexts=p list of smaller one-dimensional 
ELSE curr’ .prev .next:=p; 
IF curr=NIL THEN last:=p ELSE curr” .prev:=p; arrays on the heap, or even a 
error:=False; large disk file. In a large program, 
END the number of direct array refer- 
ELSE asd ences would be huge, and the pro- 
aaa — cess of inserting and debugging 
all of the changes needed to con- 
PROCEDURE delete_rec; vert the program for execution on 
{deletes the last record found using one of the FIND rtns.} a PC could take months. A unit 
a ila consisting of a pair of array refer- 
IF found AND (curr<>NIL) THEN ence routines called GET and 
BEGIN SET can hide the array’s imple- 
WITH curr” DO mentation, and make changing 
sa it eee eeek Diane aeons the data structure much easier 
IF curr=first THEN avrskoaratt ELSE prev’ .next:=next; when ep eee — arog os 
IF curr=last THEN last:=prev ELSE next” .prev:=prev; different systems with different 
dispose(curr); restrictions on data size and rep- 
END; resentation. Turbo Pascal is not 
ag available for mainframes, of 
" course, but even in the absence of 
PROCEDURE change_rec{rec:Addr}; units, data structure references 
{replaces the last record found using one of the find rtns can be kept out of the main pro- 
Pe rec.) gram. The larger principles are 
IF found AND (curr<>NIL) THEN Na aD te Waal Oty AEA RS aay 
curr*.az:=rec; environment. 
END; When properly used, units offer 
RE See a number of advantages to the 
UCI C SCE : programmer. They allow pro- 
ae the number of records in the data grams to be broken into reusable 
VAR cnt:word; p:pntr; modules, and also allow certain 
BEGIN details of the program’s design to 
pee be hidden from the main pro- 
Oarie CponIL) DO gram. Hiding data structure details 
BEGIN in this way makes it easier to de- 
p:=p*.next; sign and implement programs 
ent:=cnt+1; cleanly, to modify programs as 
END; they evolve, and to port programs 


size:=cnt; 


among various machine 
END; 


environments. @ 


FUNCTION full {:Boolean}; 


{FULL will be false if space remains in the data structure.} Marshall Brain is a Pascal instructor 
ETF MemAvai l<SizeOf(Addr) THEN full:=True ELSE full:-False; NAS Se rae 
END; ; : : He can be reached at Box 37224, 


Raleigh, North Carolina 27627. 


{initialization code for the unit.} 
BEGIN Listings may be downloaded from 


init; 
END. CompuServe as HIDE.ARC. 
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INTERFACING THE DOS 
PRINT SPOOLER 


Use the DOS Multiplex Interrupt to spool files for printing 
from within your Turbo Pascal programs. 


Duane L. Geiger 


Version 3.0 of DOS provides application 
programs with an interface to some of the 
utility programs included with DOS. This 
interface—the DOS Multiplex Interrupt 
($2F)—allows your Turbo Pascal pro- 
rr grams to inspect the installed state of a 
selected few of these utilities. 


WIZARD 


PRINT.COM 

One of the utilities included with DOS that makes 
use of the Multiplex Interrupt is PRINT.-COM, a resi- 
dent program that manages print queues. This pro- 
gram allows normal foreground processing to con- 
tinue while files are printed as a background task. 
PRINT was the first documented utility to use the 
Multiplex Interrupt. Using the Multiplex Interrupt in 
conjunction with PRINT allows you to submit a file 
to PRINT for printing, remove a file or files from the 
print queue, or inspect the current status of the print 
queue. 

When installed with its default settings, PRINT 
uses a little more than 5K of memory for the resident 
portion of the program and the print queue. PRINT 
has several command line installation options that 
change the amount of memory reserved for PRINT’s 
operation. Refer to your DOS reference manual for 
a complete discussion and examples. 


THE MULTIPLEX INTERRUPT 


The Multiplex Interrupt ($2F) was introduced into 
the DOS documentation in version 3.0 as a standard 
way to inspect the installed status of a few of the util- 
ities bundled with DOS. The use of the Multiplex 
Interrupt may be compared to the use of the DOS 
services interrupt ($21), except that instead of provid- 
ing the familiar DOS services, the Multiplex Inter- 
rupt furnishes the services of DOS utility programs. 
As of this writing, four DOS utility programs are 
documented as supporting the Multiplex Interrupt: 
the Print Queue Manager (PRINT), the Route Disk 
I/O utility (ASSIGN), the File Sharing utility 
(SHARE), and the Disk Spanning utility (APPEND). 


This interrupt provides an excellent method for 
these utilities to handle their respective functions 
and provide “hooks” for application programs. In 
order to avoid conflict with other utilities, each sup- 
ported utility is assigned a unique identification 
code, which is reserved by standardizing the inter- 
rupt function call in the documentation. 


MULTIPLEX CALLING CONVENTION 


The Multiplex Interrupt uses a standard calling con- 
vention—registers are loaded in a consistent manner 
and the interrupt is performed. In order to call the 
Multiplex Interrupt, load the AH register with the 
appropriate identification code for the utility pro- 
gram you want to access (see Table 1). Then load 

the AL register with the selected function code (see 
Table 2), and finally, make the interrupt call: 


Intr($2F,Regs); 


When the call returns to your program, check the 
carry flag. If the carry flag is set, an error has oc- 
curred. The appropriate error code appears in reg- 
ister AX (see Table 3). 

All of the utility programs listed in Table 1 support 
the Get Installed State function code (AL=0). Only 
PRINT supports the additional (AL) functions listed 
in Table 2. As an example of Get Installed State, see 
the ShareInstalled function in the unit SPOOL.PAS 
(Listing 1). ShareInstalled loads the registers with 
appropriate values and issues the Multiplex Inter- 
rupt. This function tests the version of DOS; if 
the appropriate version of DOS is running, 
ShareInstalled issues the Get Installed State com- 
mand for SHARE (AH=$10, AL=$00). If SHARE 
is resident, the function returns a value of True. 


PRINT QUEUE MANAGEMENT 


The print queue manager (PRINT:COM) supports 
the functions that allow your programs to take direct 


continued on page 42 
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TURBO PASCAL 


THE PRINT SPOOLER 
continued from page 41 


LISTING 1: PR.PAS 


PROGRAM Pr; { Multiplex Interrupt Test 
€SRo 937) = = gla eh pe 
{$M 16384,0,655360 > 


TO ACCESS THE RESI- USE 
DENT PORTION OF: AH VALUE: 


{ 
PR.PAS - Interrupt $2F (Multiplex) Demonstrati PRINT $01 
: Pp 4 ¢ iplex) Demonstration ASSIGN $02 
= SHARE $10 
D Ls G 
‘ uane eiger APPEND $B7 
USES DOS.CRT.S l: Reserved by DOS $00-$BF 
. pres Available values $C0-$FF 
VAR 
Installed : Boolean; { Print Spooler Installed Switch Table 1. Multiplex Interrupt ID codes. 
Name : PathName; { Full Path and Filename 
Ch : Char; { Used to Pause the Program 2 
The multiplex 
BEGIN 


{ The first demonstration is to see if SHARE is installed. The } 
{ same technique used to detect SHARE can also be used to test } 
{ any utility which supports Get Installed State. } 


interrupt was intro- 
duced into the DOS 


documentation in 


Instal led:=SharelInstal led; { If SHARE is installed > 
WriteLn('Share Installed: ',Installed,' Error:',Error); 


{ The next part of the program simply checks to see if you have } 
{ PRINT.COM installed, and if you have DOS 3.0 or greater. > 
{ If either condition is not met, an error is returned. } 


version 3.0 asa 


Instal led:=SpoolerInstal led; { If Print Spooler installed } standard way to 


WriteLn('PRINT.COM Installed: ',Installed,' Error:',Error); ° ° 
IF NOT Installed THEN Halt(Error); { Can't continue this program >| | Lmspect the installed 


{ Now queue up a name to the print program. » status of a few 
Name:='PR.PAS'; { Name of actual file to queue} Re 
Write('Submitting: ',Name,' - '); { Print a test message > DOS utilities. 
SpoolerSubmit (Name); { Submit name to spooler > 

IF OK THEN WriteLn('Successful')  { Everything went OK } 

ELSE WriteLn('Error encountered:',Error); { Display error message} control of the print queue Vou 
Name:='SPOOL.PAS'; { Submit another file to print}| | May submit files to the print ; 
Write('Submitting: ',Name,' - '); { Display a message }| | queue, delete files from the print 
SpoolerSubmi t (Name); { Submit name(s) to spooler } queue, and hold and release the 
IF OK THEN WriteLn('Successful') { Did it work correctly? > rint queue. However, while 
ELSE WriteLn('Error encountered:',Error); { or produce an error } is 4 ; : 


PRINT.COM is printing from the 


WriteLn('Press Any Key to Continue'); { Now printing PR.PAS >| | queue, you cannot directly print 
REPEAT UNTIL KeyPressed; { Wait for a keystroke }| | files to the printer because this 
REPEAT Ch:=Readkey; UNTIL NOT KeyPressed; { Flush keyboard }| | would cause quite a mess at the 


SpoolerStatusRead; { Pause and display queue 2 peer itself. Ifa bene ae 5 
IF OK THEN WriteLn('Successful') { OK on status read }| | tempts to print to the printer while 
ELSE WriteLn('Error encountered:',Error); € An Error of some type} PRINT.COM is printing, a critical 
error occurs. 

The first step in providing 
queue management support is to 
report the status of the queue 


WriteLn('Press Any Key to Continue'); { Another pause } 
REPEAT UNTIL KeyPressed; { Get a keystroke } 
REPEAT Ch:=Readkey; UNTIL NOT KeyPressed; { Flush keyboard again } 


Write('Spooler Release - '); { Print test message }| | manager. The sample unit pro- 
SpoolerStatusEnd; { Start up the print job again}| | vides this facility by returning a 
IF OK THEN WriteLn('Successful') { It went OK > Boolean value from function 


j 1 st . j j ‘ 
ELSE WriteLn('Error encountered:',Error); € or it failed somehow } SpoolerInstalled. This function 


Write('Canceling: ALL - '); { Message declaring intent  }| | tests that the appropriate version 
SpoolerCancelAll; { Cancel entire print queue }|| of DOS is running, then issues the 
IF OK THEN WriteLn('Successful') { It was successful or > Get Installed State command for 
ELSE WriteLn('Error encountered:',Error); € it somehow failed > 


PRINT (AH=$01, AL=$00). If the 
queue manager is installed, the 


Name:='Pr.Pas'; { Cancel individual filename } 
Write('Canceling: ',Name,' - ');  { Display test message }| | function returns True. 
SpoolerCancel (Name); { Cancel by name } 

IF OK THEN WriteLn('Successful') { It will work > 

ELSE WriteLn('Error encountered:',Error); € or fail > 


END. 
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The next step in queue man- 
agement support is submission of 
a file to the queue manager. The 
procedure SpoolerSubmit in the 
sample unit provides this facility. 
You must call this procedure with 
the full file- and pathname of the 
print image file to be placed in 
the print queue. Note: You may 
not use the DOS wildcard charac- 
ters (*,2) in the submit filename 
string. 


While 
PRINT.COM is 
printing from the 
queue, you cannot 
print directly to the 
printer, because 
this would cause 
quite a mess at the 
printer itself. 


REGISTER AL FUNCTION 


FUNCTION DESCRIPTION 
CODE 
$00 Get Installed State 
$01 Submit File 
$02 Cancel File 
$03 Cancel All Files 
$04 Status Read 
$05 Status End 


$F8-$FF Reserved by DOS 
Table 2. Multiplex Interrupt function codes. 


REGISTER AX ERROR 
ERROR CODES DESCRIPTION 


Invalid Function 

File Not Found 

Path Not Found 

Too Many Open Files 
Access Denied 
Queue Full 

Busy 

Name Too Long 
Invalid Drive 


—e OOO, WON 


orn 


NOTE: On an error, the Carry Flag is set. 


Table 3. Multiplex Interrupt error codes. 
continued on page 44 


LISTING 2: SPOOL.PAS 


UNIT Spool; { PRINT.COM Spool Utility 

‘ SPOOL.PAS - Queue Management Routines 

: Duane L. Geiger 

ene { Globally Known Types and Variables 


Uses 


DOS; { Standard TP4 DOS Unit d 


TYPE 


PathName = STRING([64]; { Path and Filename String Area > 


VAR 
OK 
Error 


Boolean; 
Byte; 


: { Global Flag for Success Tests > 
C { Error Flag if Not OK on Interrupt} 
{ Possible error conditions encountered in Functions 1 through 5 
{ Carry Flag is Set and Register AX contains: 
= Function Code Invalid 
File Not Found 
Path Not Found 
Too Many Open Files 
Access Denied 
Queue Full 
Spooler Busy 
Name Too Long 
Drive Invalid 


AAAABADRAN 
OOUEWN— 

nunwnhnt nwt 

ln clin clin atin atlantic in lin tli al 


FUNCTION 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


SpoolerInstalled : Boolean; 
SpoolerSubmit( Name : PathName ); 
SpoolerCancel( Name : PathName ); 
SpoolerCancelAll; 
SpoolerStatusRead; 
SpoolerStatusEnd; 

FUNCTION 


Sharelnstalled : Boolean; 


IMPLEMENTATION 


TYPE 


ZName ARRAY[1..64] OF Byte; { ASCIIZ FileName Area > 


VAR 
Regs 
Major, 
Minor : 


: Registers; { Registers for DOS Unit Interface 
{ Major version of DOS installed 


{ Minor version of DOS 


Vvvw 


Word; 


PROCEDURE ASCIIZ( Name : PathName; VAR PassName : 
{ Create an ASCIIZ Name from Pascal String } 
TYPE 
ASCIIZName = RECORD 
LnByte : Byte; 
NStr : ZName; 
END; 


ZName ); 


{ Use the structure of string } 
{ Length of the string > 
{ Actual characters in string } 
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VAR 
Nme : ASCI1ZName ABSOLUTE Name; 
BEGIN 
Nme.NStr[Nme.LnByte+1] := $00; 
PassName := Nme.Nstr; 
END; 


FUNCTION SpoolerInstalled : Boolean; 
{ TRUE if Spooler Installed, Otherwise FALSE and an Error 


{ AL Contains installed Status: 
< $00 = Not installed, OK to install 
{ $01 = Not installed, Not OK to install 
€ $FF = Installed 
BEGIN 
{ First test to see if DOS 3. 
IF (Major >= 3) AND { 
(Minor >= 0) THEN { 
ELSE BEGIN { 
Error em Tz € 
SpoolerInstalled := False; { Function Return 
Exit; { Immeditate Exit 
END; { of Error Condition 
{ Now test to see if resident 
Error := 0; 
Regs.AH := $01; 
Regs.AL := $00; 
Intr($2F,Regs); 
IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set/Error 
SpoolerInstalled := False; { Set 
Error := Regs.AX; 
END { of Error Condition 
ELSE 
SpoolerInstalled := (Regs.AL=$FF); { $FF Indicates Installed 
END; 


PROCEDURE SpoolerSubmit( Name : 
TYPE 
Packet = RECORD 
Level : Byte; 


{ Point the string 


{ Null terminate the string 
{ Return the ASCIIZ portion 


wWMVyvVyw 


00 or Greater is Running 

It's version 3.0 or greater 

Null then (It's OK for $2F) 
This is not a good version of DOS 
Not Install and Can't Run 


dite clin ciliate atin ailiin aiiin al 


portion of PRINT.COM is installed. 
{ Reset System Wide Error 

{ Select Resident Portion of Print 
{ Request the Installed Status 

{ Perform Status Interrupt 


‘Not Installed! Switch 
{ Load the Error Encountered 


{ The Interrupt Succeeded 


ll tlle ln ctl atin alin alien in alin iin al 


PathName ); 


{ Submit Packet for PRINT.COM 
{ Printer Level 
{ 


wen 


NPtr : Pointer; Pointer to ASCIIZ name 
END; 
VAR 
SubPack : Packet; { Submit filename packet } 
PassName : Zname; { ASCIIZ filename to pass > 
BEGIN 
Error := 0; { Clear the Global Error Flag } 
OK := True; { Assume it will work } 
ASCIIZ( Name , PassName ); { Build an ASCIIZ name to Pass} 
SubPack.Level := 0; { Print 'Level' } 
SubPack.NPtr := @PassName; { Pointer to Filename a 
Regs.AH := $01; { Resident portion of PRINT } 
Regs.AL z= $01; { Submit a file to PRINT } 
Regs.DS z= Seg(SubPack); { Segment pointer to packet } 
Regs .DX := Ofs(SubPack); { Offset to submission > 
Intr($2F ,Regs); { MultiPlex interrupt > 
IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set/Error } 
OK := False; { Error in file submission > 
Error := Regs.AX; { Load the Error Variable } 
END; { of Error Handling } 


END; 
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THE PRINT SPOOLER 
continued from page 43 


SpoolerSubmit prepares a data 
packet and passes the data packet's 
address to PRINT. This packet 
contains an ASCIIZ string for the 
full filename and a level code, 
which must be set equal to zero. 
(Currently, zero is the only level 
code accepted by the PRINT pro- 
gram. I suspect that this level code 
was originally intended to priori- 
tize the print queue, but prioriti- 
zation was never actually imple- 
mented in the PRINT program.) 
To complete the submission pro- 
cess, the registers are set 
(AH=$01, AL=$01, and DS:DX is 
loaded with the address of the 
submission packet), and the Multi- 
plex Interrupt is issued. If success- 
ful, Boolean variable OK is set to 
True; otherwise, OK is set to False 
and the global variable Error is 
set to the value returned in regis- 


ter AX. 


I suspect that 
the level code was 
originally intended 
to prioritize the 
print queue, but 
prioritization was 
never actually 


implemented in the 


PRINT program. 


The procedures SpoolerCancel 
and SpoolerCancelAll handle an- 
other important aspect of queue 
management—the removal of 
files from the print queue. Unlike 
the submit function, the cancel 
function accepts wildcard charac- 
ters as part of the filename string. 
To cancel a single filename 
from the print queue, call 
SpoolerCancel with the name of 
the file to be removed. To cancel 
all files in the print queue, use 
SpoolerCancelAll. If successful, 


OK becomes True; otherwise, OK 
is set to False and register AX is 
copied to the Error global vari- 
able. When files being printed are 
canceled, either the message “File 
[filename.ext] canceled by opera- 
tor” or “All files canceled by oper- 
ator” is printed on the printer and 
a page eject occurs. 


The first entry 
in the queue is the 
name of the file 
currently printing, 
and the end of the 
queue is marked by 
an entry whose first 
character is a null 


character. 


The remaining procedures 
you'll need to control the print 
queue are SpoolerStatusRead and 
SpoolerStatusEnd, which let you 
examine the current contents of 
the queue and resume printing. 

SpoolerStatusRead pauses the 
print queue printing activity and 
displays the filenames currently 
pending in the queue. As part of 
the status read function (AL = 
$04), a pointer to the first file- 
name in the print queue is re- 
turned in registers DS:SI. The 
print queue consists of a series of 
64-byte entries, with each entry 
terminated by a null character 
($00). The first entry in the queue 
is the name of the file currently 
printing, and the end of the 
queue is marked by an entry 
whose first character is a null 
character. You may modify 
SpoolerStatusRead to return only 
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- 


{ Remove a Filename, Wildcards 
VAR 
PassName : Zname; 


BEGIN 
Error := 0; 
OK z= True; 
ASCIIZ(Name, PassName); 
Regs.AH := $01; 
Regs.AL := $02; 
Regs.DS := Seg(PassName); 
Regs.DX := Ofs(PassName); 
Intr($2F ,Regs); 


IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN 


IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set if Error 


PROCEDURE SpoolerCancel( Name : 


PathName 


are allowed } 


{ 


AAADBAAADA 


OK := False; { 
Error := Regs.AX; £ 
END; € 
END; 
PROCEDURE SpoolerCancelAll; 
{ Remove all names from print queue } 
BEGIN 
Error := 0; € 
OK := True; € 
Regs.AH := $01; { 
Regs.AL := $03; € 
Intr($2F,Regs); { 
OK := False; { 
Error := Regs.AX; { 
END; { 
END; 


PROCEDURE SpoolerStatusRead; 


{ Pause the Spooler and Read the names 
VAR 
QPtr : ~“ZName; € 
Idx =: LongInt ABSOLUTE QPtr; { 
I : Byte; € 
Name : PathName; { 
BEGIN 
Error := 0; 
OK := True; 
Regs.AH := $01; 


Regs.AL := $04; 
Intr($2F ,Regs); 


IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set if Error 


OK := False; 
Error := Regs.AX; 
END 
ELSE BEGIN 


{ This section displays the names of all of the files that are } 
{ currently in the print Queue. 
{ this PROCEDURE to return the pointer to the names and bypass } 


{ this display routine. 


AADBAM 


€ 
€ 
€ 
€ 


If you want control, 


; 


ASCIIZ FileName to Pass 


Clear the Global Error Flag } 
Assume it will work z 
Build an ASCIIZ name to pass} 
Resident Portion of PRINT } 
Cancel a File in print queue} 
Pointer to the ASCIIZ Name } 
Offset to ASCIIZ Name 
Multiplex Interrupt 
{ Flags Set/Error 
Error in File SubMission 
Load the Error Variable 
of Error Handling 


Clear the Global Error Flag 
Assume it will work 
Resident Portion of Print 
Cancel All Files In Queue 
MultiPlex Interrupt 


Error in File Submission 
Load the Error Variable 
of Error Handling 


in ciliate iin in cin ain aiid 


> 

Pointer to ASCIIZ String 
Index Pointer 

String Index 
Constructed File Name 


Clear the Global Error Flag 
Assume if will work 
Resident Portion of Print 
Hold for Status Read 
MultiPlex Interrupt 


d 
> 
> 
Be 
> 
> 
Error in File SubMission } 
Load the Error Variable > 
of Error Handling Ay 
Display the Queue > 


modify } 
} 
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QPtr := Ptr( Regs.DS , Regs.SI );{ Point to First Name in Queue} 
WHILE QPtr°[1] <> $00 ) DO BEGIN ({ Start a Display Loop 
I := 1; Name := ''; { Index Pointer 
WHILE( QPtr°[I] <> $00 ) DO BEGIN ({ Start displaying Names 
Name := Name + Chr( QPtr°[I] );{€ Build the Name String 
I := Succ(1); { Point to Next Character 


MWY YVYVYVww 


END; { of a Name Character 
WriteLn(Name); { Display the Name just built 
Idx := Idx + 64; { Point to Next 64 Bytes 
END; { of Display Loop 
END; { of Queue Display } 
END; { of SpoolerStatusRead d 


PROCEDURE SpoolerStatusEnd; 
{ Clear the Paused Condition } 


BEGIN 
Error := 0; Clear the Global Error Flag 
OK := True; Assume if will work 


Resident Portion of Print 
Regs.AL := $05; Clear Status Read 


> 

d 

Regs.AH := $01; > 
> 

Intr($2F ,Regs); MultiPlex Interrupt > 
> 

> 

) 

> 


AAADA 


IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set if Error 
OK := False; { Error in File SubMission 
Error := Regs.AX; { Load the Error Variable 

END; { of Error Handling 

END; 


FUNCTION ShareInstalled : Boolean; 
BEGIN 


{ First test to see if DOS 3.00 or greater is running yy 
IF (Major >= 3) AND { It's version 3.0 or greater Bf 
(Minor >= 0) THEN { Null then (It's OK for $2F) } 
ELSE BEGIN { This is not a good version of DOS} 
Error s=) 1s { Not Install and Can't Run > 
ShareInstalled := False; { Function Return > 
Exits { Immeditate Exit BZ 
END; { of Error Condition > 
{ Now test to see if resident portion of SHARE is installed. > 
Enror <= 0; { Reset System Wide Error > 
Regs.AH := $10; { Select resident portion of SHARE } 
Regs.AL := $00; { Request the installed status 3 
Intr($2F ,Regs); { Perform Status Interrupt > 
IF ((Regs.Flags AND FCarry) <> 0) THEN BEGIN { Flags Set if Error} 
ShareInstalled := False; { Set 'Not Installed' switch > 
Error := Regs.AX; { Load the Error Encountered > 
END { of Error Condition > 
ELSE { The interrupt succeeded > 
SharelInstalled := (Regs.AL = $FF); { $FF indicates installed } 
END; 
BEGIN 
{ First test to see if DOS 3.00 or Greater is Running > 
Regs.AH := $30; { Request Version Number > 
MsDos(Regs); { Perform Interrupt $21 > 
Major := Regs.AL; { Extract major version of DOS } 
Minor  := Regs.AH; { Extract minor version of DOS > 
END. 
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THE PRINT SPOOLER 
continued from page 45 


the pointer to the print queue so 
that you can perform your own 
decoding, rather than allow the 
procedure to blindly display the 
names in the print queue. 

Finally, SpoolerStatusEnd re- 
leases the print queue manager 
from its paused state after a 
status read function call. 
SpoolerStatusEnd, or any other 
function call to PRINT through 
the Multiplex Interrupt, releases 
the queue and resumes printing. 
SpoolerStatusEnd is also used to 
display the contents of the print 
queue when no other action is to 
be taken. 


You may modify 
SpoolerStatusRead 
to return only the 
pointer to the print 
queue so that you 
can perform your 
own decoding, 
rather than allow 
the procedure to 
blindly display the 
names in the print 
queue. 

With this set of functions and 
procedures, you can implement 
print spool management in your 
everyday applications. After all, 
unless you need a long coffee 
break, why wait for reports to fin- 
ish printing before you regain 
control of your computer? 
Duane L. Geiger, author of Tele- 
Mark, has been an independent devel- 
oper and consultant for the last nine 
years. He lives and works in Newport, 
Oregon. 


Listings may be downloaded from 
CompuServe as SPOOL. ARC. 


EXPLORING THE INTERRUPT 


VECTOR TABLE 


The first 1K of PC RAM is the gatekeeper to your system’s 
DOS and BIOS resources. Feel free to look ... and touch 


carefully. 


Jeff Duntemann 


Most people think that DOS is the con- 
trolling hand within the IBM PC. While 
largely true, this idea doesn’t credit the 
assistance of the IBM ROM BIOS, which 
does much of the work for DOS. Both 
DOS and the ROM BIOS are called 
through software interrupts. 


YO! 


An interrupt is a tap on the CPU’s shoulder, telling 
the CPU that it must pay attention to something else 
now. Interrupt mechanisms have always been part of 
microprocessor systems. Until the development of 
the 8086 and 8088, all interrupts were hardware 
interrupts. 

Hardware interrupts work this way: An electrical 
signal on one pin of the CPU chip causes the CPU 
logic to save the program counter, code segment reg- 
ister (CS), and flags register. The CPU is then free to 
service the request from outside the chip to execute 
some bit of code unrelated to its ongoing task. Once 
the request for service is satisfied, the CPU restores 
the registers it had saved and picks up its ongoing 
task as though nothing had happened. 

With the 8086 family architecture, Intel presented 
the concept of the software interrupt. Software inter- 
rupts work exactly the same way as hardware inter- 
rupts, except that the triggering request is a machine 
instruction (software) rather than an electrical signal 
on a CPU pin (hardware). 

Software interrupts provide standard entry points 
to system software. When any kind of interrupt 
happens, the CPU first saves essential registers, and 
then performs a “long jump” to the location of the 
interrupt service routine somewhere in memory. 

The way that the CPU locates this interrupt service 
routine is critical. The 8088 recognizes 256 inter- 
rupts, numbered from 0 to 255. When an interrupt 
happens, the CPU must receive the number of the 
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Editor’s Note: This article is excerpted from the forthcoming 
book, Complete Turbo Pascal, Third Edition, by Jeff Duntemann. 


Complete Turbo Pascal, Third Edition is scheduled for July, 1988, 
publication by Scott, Foresman & Company. 


requested interrupt. For hardware interrupts, this 
number comes from the interrupt priority controller 
chip outside the CPU. For software interrupts, the 
interrupt number is built into the interrupt instruc- 
tion. For example, the 8088 instruction INT 21 
triggers software interrupt 21H. 

The first 1024 bytes of the PC memory map are 
reserved for interrupt vectors. “Vector” can be taken 
to mean “pointer,” and pointers are exactly what 
occupy those 1024 bytes of memory. Each of the 256 
different interrupts has its own 4-byte region of this 
1024-byte memory block (256 X 4 = 1024). This 
4-byte region contains a 32-bit pointer to the first 
instruction of the interrupt’s service routine. 

The first four bytes of 8088 memory contain the 
vector for interrupt 0. The next four bytes of memory 
contain the vector for interrupt 1, and so on up to 
255 (see Figure 1). Obviously, if the CPU knows the 
interrupt number, it can multiply that number by 
four and go immediately to the interrupt vector for 
any given interrupt. The first two bytes of the inter- 
rupt vector are the program counter value for the 
start of the service routine, and the second two bytes 
are the code segment value where that service rou- 
tine exists. The CPU need only load the code seg- 
ment value into the CS register and then load the 


[trier PTnverrape 2 
[Ofer Segment | Offset | Segment | Offset | _ 
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Memory addresses —> 


0000:0000 


Figure 1. The structure of the 8088 interrupt vector table. 
There are 256 vectors in the table, each consisting of 4 bytes 
that represent the service routine segment and offset in the 
order shown. 
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TURBO PASCAL 


Interrupt vector utility 


by Jeff Duntemann 
Turbo Pascal V4.0 
Last update 3/15/88 


This program allows you to inspect and change 8086 interrupt 
vectors, and look at the first 256 bytes pointed to by any 
vector. This allows the spotting of interrupt service 
routine "signatures" (typically the vendor's copyright 
notice) and also indicates when a vector points to an IRET. 


From: COMPLETE TURBO PASCAL, 3E by Jeff Duntemann 
Scott, Foresman & Co., Inc. 1988 ISBN 0-673-38355-5 


PROGRAM Vectors; 


USES DOS; { For GetIntVec and SetIntVec } 


{$V-} { Relaxes type checking on string lengths } 
CONST 
Up = True; 


TYPE 
String80 
Block 
PtrPieces 


String (80) ; 
ARRAY (0..255] OF Byte; 
ARRAY [(0..3] OF Byte; 


VAR 

I : Integer; 
VectorNumber : Integer; 
Vector : Pointer; 
VSeg, VOfs : Integer; 
NewVector : Integer; 
MemB Lock : Block; 

ErrorPosition : Integer; 
Quit : Boolean; 
Command : String80; 
CommandChar =: Char; 


PROCEDURE Stripwhite(VAR Target : String); 
CONST 
Whitespace : SET OF Char = (#8,#10,#12,#13,' ']; 


BEGIN 
WHILE (Length(Target) > 0) AND (Target{1] IN Whitespace) DO 
Delete(Target,1,1) 
END; 


PROCEDURE WriteHex(BT : Byte); 


CONST 
HexDigits : ARRAY[O..15] OF Char = '0123456789ABCDEF'; 


VAR 
BZ : Byte; 


:= BT AND SOF; 
:= BT SHR 4; 
Write(HexDigits (BT) ,HexDigits[BZ)) 
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ed 
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program counter value into the program counter 
register—and it’s off and running the interrupt ser- 
vice routine. 

The important fact here is that the code that 
wishes to use a software interrupt service routine 
doesn’t need to know where that routine is located 
in memory—the code only needs to know the inter- 
rupt number. Indeed, the actual location of the ser- 
vice routine can change over time as the routine is 
altered or expanded. As long as the computer’s boot 
or startup code stores the correct interrupt vectors 
into the lowermost 1024 bytes of memory, software 
interrupt service routines may be located anywhere 
and still be used quickly and easily by application 
programs. 

This is the spirit of the IBM PC’s ROM BIOS. The 
BIOS is a collection of software interrupt service rou- 
tines stored in ROM at the very top of the 8088's 
memory address space. The interrupt numbers are 
assigned according to the general function perform- 
ed by the interrupt service routine. For example, 
interrupt 16 (10H) controls video services for the PC. 
Interrupt 22 (16H) controls access to the keyboard. 

Not all software interrupts are reserved for the 
use of the ROM BIOS; most of them are not used 
at all. DOS uses a few software interrupts, and the 
Microsoft and Logitech mouse drivers use one. Quite 
a few peripheral driver programs, in fact, make use 
of software interrupts. The PC as we know it would 
have been impossible without them. 


GetIntVec AND SetIntVec 


The interrupt vector table can be explored with 
DEBUG, but a fairly simple program makes the vec- 
tors easier to read and change. VECTORS.PAS (List- 
ing 1) provides a utility called Vectors that displays 
and changes interrupt vectors, and also displays a 
hex dump of the first 256 bytes of memory pointed to 
by a vector. Changing an interrupt vector can be 
strong medicine, and shouldn’t be done unless you 
know exactly what you're doing. Altering the timer 
tick interrupt carelessly freezes your machine solid 
in no more than 55 milliseconds’ time. But if you 
intend to write programs that intercept interrupt vec- 
tors, Vectors can save a lot of aggravation during 
development. 

One problem in reading simple hex dumps of the 
vector table is that the vectors’ components are 
stored backward in memory from the way we human 
beings generally write them (see Figure 1). The 
offsets are stored before the segments, and the least 
significant bytes of both segments and offsets are 
stored before the most significant bytes. 

Vectors reformats the interrupt vector table for 
your eyes, and lets you perform certain useful opera- 
tions on the table. For example, it allows you to zero 


out all 32 bits of a vector, and also lets you separately 
change the offset or segment portion of any vector to 
the value of your choice. 

Vectors centers on two routines from Turbo 
Pascal’s DOS unit, GetIntVec and SetIntVec: 
PROCEDURE GetIntVec 


(IntNumber : Byte; 
VAR Vector : Pointer); 


PROCEDURE SetINtVec 
(IntNumber : Byte; 
Vector : Pointer); 


In both cases, IntNumber contains the number 
of the interrupt whose vector you wish to read or 
change, and Vector is a generic pointer containing 
the address read from or written to that vector. 
GetIntVec returns vector IntNumber in Vector; and 
SetIntVec places the address in pointer Vector in the 
vector table for interrupt IntNumber. These are 
“well-behaved” routines for reading and setting vec- 
tors from the interrupt vector table. We say “well- 
behaved” because there are “ill-behaved” ways to 
alter the vector table—by use of the MEM, MEMW, 
and MEML statements. 

Why are MEM, MEMW, and MEML ill-behaved? 

Well, think about this: Suppose you're in the midst 
of altering a vector in the table and you have half of 
a new value written; then something somewhere in 
the system calls that interrupt. At the moment when 
the CPU recognizes the interrupt, you may already 
have a new segment in place, but you may not yet 
have overwritten the old offset. The CPU sends exe- 
cution charging off on this half-baked vector (which 
points into the middle of a data buffer), starts execut- 
ing data as code, and freezes the machine solid. 

DOS has a pair of functions for reading and set- 
ting interrupt vectors correctly that first disable inter- 
rupts before reading or altering a vector. Only when 
the vector is completely read, or completely changed, 
will DOS re-enable interrupts. That way, your pro- 
grams will not end up reading a half-correct vector, 
or (much worse) allowing the CPU to transfer con- 
trol to a half-correct vector. 


PEEKING AT ISRs 


The Vectors utility knows another trick—it can pro- 
vide a look at what any vector is pointing to. Any 
initialized interrupt vector points to an interrupt ser- 
vice routine (ISR) of some sort. On command, 
Vectors displays a hex dump of the first 256 bytes 
of memory pointed to by any given interrupt vec- 
tor. Those wild-eyed folks who read 8086 binary 
machine code in their heads can track the logic of 
simple service routines. The rest of us can look for 
interrupt service routine “signatures,” typically in the 
form of copyright notices embedded in the binary 
machine code. For example, if you have the Logitech 
Mouse driver loaded, Vectors shows you the 
Logitech signature at an offset of 16 bytes into the 
driver, pointed to by interrupt 51 (33H). 

Vectors tests every vector that it displays, and indi- 
cates whether the vector points to a byte containing 
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FUNCTION ForceCase(Up : BOOLEAN; Target : String) : String; 


CONST 
Uppercase : 


Lowercase : 


VAR 
I: INTEGER; 


BEGIN 

IF Up THEN FOR I <= 1 TO Length(Target) DO 
IF Target(I] IN Lowercase THEN 

Target(I] := UpCase(Target[I]) 

ELSE { WULL > 

ELSE FOR I := 1 TO Length(Target) DO 

IF Target[I] IN Uppercase THEN 

Target(I) z= Chr(Ord(Target [1] )+32); 


ForceCase := Target 
END; 
Procedure ValHex(HexString : String; ” 
VAR Value : LongInt; 


VAR ErrCode : Integer); 


VAR 


HexDigits : String; 
Position : Integer; 
PlaceValue : Longint; 
TempValue : LongInt; 
I : Integer; 


BEGIN 

ErrCode := 0; TempValue := 0; PlaceValue := 1; 

HexDigits := '0123456789ABCDEF'; 

Stripwhite(HexString); { Get rid of leading whitespace } 

IF Pos('$',HexString) = 1 THEN Delete(Hexstring, 1,1); 

HexString := ForceCase(Up,HexString); 

IF (Length(HexString) > 8) THEN ErrCode := 9 

ELSE IF (Length(HexString) < 1) THEN ErrCode := 1 

ELSE 

BEGIN 

FOR I z= Length(HexString) DOWNTO 1DO { For each character } 

BEGIN 

{ The position of the character in the string is its value:} 
Position := Pos(Copy(HexString,1,1),HexDigits) ; 
IF Position = O THEN { If we find an invalid character...) 


BEGIN 
ErrCode := 1; { ...set the error code... } 
Exit { ...and exit the procedure } 
END; 


{ The next line calculates the value of the given digit } 
{ and adds it to the cumulative value of the string: } 


TempValue := TempValue + ((Position-1) * PlaceValue); 
PlaceValue := PlaceValue * 16; { Move to next place } 
END; 
Value := TempValue 


END 
END; 


PROCEDURE DumpBlock(XBlock : Block); 


VAR 
I,J,K : Integer; 
Ch : Char; 


BEGIN 
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FOR 1:=0 TO 15 DO 
BEGIN 
FOR J:=0 TO 15 DO 
BEGIN 
Wri teHex(Ord(XBlock [(1*16)+J] )); 
Write¢' ') 
END; 
Write(' |"); 
FOR J:=0 TO 15 DO 
BEGIN 
Ch:=Chr(XBlock [(1*16)+J] ); 
IF ((Ord(Ch)<127) AND (Ord(Ch)>31)) 
THEN Write(Ch) ELSE Write('.') 
END; 
Writeln¢'|") 
END; 
FOR 1:=0 TO 1 DO Writeln('') 
END; { DumpBlock > 


{ Do a hexdump of 16 lines of 16 chars } 


{ Show hex values } 


{ Bar to separate hex & ASCII } 
{ Show printable chars or '.' > 


IPROCEDURE ShowHelp; 


BEGIN 
Writeln; 
Writeln('Press RETURN to advance to the next vector.'); 
Writeln; 
Writeln 
('To display a specific vector, enter the vector number (0-255)'); 
Writeln 
(‘in decimal or preceded by a "$" for hex, followed by RETURN.'); 
Writeln; 
Writeln('Valid commands are:'); 
Writeln; 
Writeln 
('D : Dump the first 256 bytes pointed to by the current vector'); 
Writeln 
('E : Enter a new value (decimal or hex) for the current vector'); 
Writeln('H : Display this help message‘); 
Writeln('Q : Exit VECTORS '); 
Writeln('X : Exit VECTORS '); 
Writeln('Z : Zero segment and offset of the current vector'); 
Writeln('? : Display this help message'); 
Writeln; 
Write('The indicator ">>IRET" means the vector'); 
Writeln(' points to an IRET instruction'); 
Writeln; 
END; 


PROCEDURE DisplayVector(VectorNumber : Integer); 
VAR 


Bump : Integer; 
Chunks : PtrPieces; 


Vector : Pointer; 
Tester : “Byte; 
BEGIN 


GetIntVec(VectorNumber ,Vector);{ Get the vector } 
Tester := Vector; 

Chunks := PtrPieces(Vector); 
Write(VectorNumber : 3,' $'); 
Wri teHex(VectorNumber ); 
Write(' ('); 

Wri teHex(Chunks [3] ); 
Wri teHex(Chunks [2] ); 
Write(':'); 

Wri teHex(Chunks (1) ); 
Wri teHex(Chunks (0) ); 
Write(']'); 


{ Cast Vector onto Chunks } 


{ Write out the chunks as hex digits > 


{ Can't dereference untyped pointer } 


IF Tester” = SCF 
THEN Write(' >>IRET ') 
ELSE Write’ ee 
END; 


{ If vector points to an IRET, say 80 } 


PROCEDURE DumpTargetData(VectorNumber : Integer); 


VAR 
Vector : Pointer; 
Tester : “Block; 


BEGIN 
GetIntVec(VectorNumber,Vector); { Get the vector > 
Tester := Vector; { Cast the vector onto e pointer to a block > 
MemBlock := Tester”; { Copy the target block into MemBlock } 
IF MemBlock(0] = SCF THEN { See if the first byte is an IRET } 

Writeln('Vector points to an IRET.'); 

Dump Lock (MemB Lock ) { and finally, hexdump the block. } 

ENO; 


PROCEDURE ChangeVector(VectorNumber: Integer); 


VAR 
Vector : Pointer; 
LongTemp, TempValue : Longint; 
SegPart,OfsPart : Word; 


BEGIN 
GetIntVec(VectorNumber ,Vector); { Get current value of vector } 
LongTemp := LongInt(Vector); { Cast Pointer onto Longint } 
SegPart := LongTemp SHR 16; { Separate pointer seg. from off. } 
OfsPart := LongTemp AND SOOOOFFFF; { And keep until changed } 
Write('Enter segment '); 
Write(' (RETURN retains current value): '); 
Read|n( Command) ; 
StripWhi te(Command); 
{ If something other than RETURN was entered: } 
IF Length(Command) > 0 THEN 
BEGIN 
Val (Command, TempValue,ErrorPosition); { Evaluate as decimal } 
IF ErrorPosition = 0 THEN SegPart := TempValue 
ELSE ( If it's not a valid decimal value, evaluate as hex: } 
BEGIN 
ValHex(Command, TempValue,ErrorPosition); 
IF ErrorPosition = 0 THEN SegPart := TempValue 
END; 
{ Reset the vector with any changes: } 
Vector := Ptr(SegPart,OfsPart); 
SetIntVec(VectorNumber , Vector); 
END; 
DisplayVector(VectorNumber); { Show it to reflect any changes } 
Writeln; 
Write('Enter offset '); { Now get an offset ) 
Write('(RETURN retains current value): '); 
Read|n( Command) ; 
Stripwhite(Command) ; 
{ If something other than RETURN was entered: } 
IF Length(Command) > O THEN 
BEGIN 
Val (Command, TempValue,ErrorPosition); {€ Evaluate as decimal > 
IF ErrorPosition = 0 THEN OfsPart := TempValue 
ELSE { If it's not a valid decimal value, evaluate as hex: } 
BEGIN 
ValHex(Command, TempValue,ErrorPosition); 
IF ErrorPosition = 0 THEN OfsPart := TempValue 
END 
END; 
( Finally, reset vector with any changes: } 
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CFH. This is the machine-code equivalent of the 
IRET (Interrupt Return) mnemonic. Pointing an 
interrupt to an IRET instruction is a safety measure 
that prevents havoc in case an interrupt occurs for 
which the vector is uninitialized. If an unused vector 
is made to point to an IRET, the worst that can 
happen if that interrupt is triggered is nothing at 
all—the IRET sends execution back to the caller 
without taking any action. 

In the best of all worlds, all unused interrupt vec- 
tors are initialized to point to an IRET. But as you'll 
see once you run Vectors, only a few vectors are so 
disarmed. Most vectors point to segment zero, offset 
zero (which is in fact an interrupt vector itself—the 
vector for interrupt 0, the first entry in the vector 
table). If such an interrupt occurs, the CPU attempts 
to execute the interrupt jump table as though it were 
code—which will almost certainly crash the machine 
hard. 

Vectors is simple in operation. It cycles through 
the 256 interrupt vectors one at a time, displaying the 
current value of the current interrupt vector, and 
then pauses for a command. “Jumping” to another 
interrupt vector is done by entering that vector’s 
value as either a decimal number or a hexadecimal 
value preceded by a “$.” 

The E command is used to change a vector value. 
E prompts individually for the segment and offset 
portion of the vector. If you don’t wish to change 
one or both of these, simply press Enter and nothing 
is altered. As with jumping to a new value, vector 
values can be entered in either decimal or hex. 

The command D dumps the 256 bytes pointed to 
by the current vector. If the first byte of the block is 
an IRET instruction, Vectors displays the string 
“>>IRET.” 

The command Z changes both the offset and seg- 
ment portion of a vector to zero. This is useful in 
cases where you're testing software that modifies 
interrupt vectors—and you may be modifying the 
wrong vectors. Zeroing a vector allows you to come 
back after your test software has run and to tell at a 
glance if the zeroed vector or vectors have stayed 
zeroed. 

Either of the commands Q or X exits Vectors to 
DOS. 

The hex format display procedure WriteHex fig- 
ures prominently in Vectors as the mechanism by 
which the interrupt vectors are displayed, and also as 
the core of a hexdump routine, DumpBlock, that 
dumps 256 bytes of memory at the location pointed 
to by the current vector. 


Listings may be downloaded from CompuServe as 
VECTOR.ARC. 


Vector 


z= Ptr(SegPart,OfsPart); 


SetIntVec(VectorNumber , Vector); 


:= False; 


VectorNumber := 0; 

Writeln( '>>VECTORS<<'); 

Writeln('By Jeff Duntemann'); 

Writeln('From the book: COMPLETE TURBO PASCAL, 3E'); 
Writeln('ISBN 0-673-38355-5'); 

ShowHelp; 


REPEAT 


DisplayVector(VectorNumber ); 
Read|n( Command) ; 
IF Length(Command) > 0 THEN 
BEGIN ‘ 
{ See if a number was typed; if one was, it becomes the } 
{ current vector number. If an error in converting the ) 
{ string to a number occurs, Vectors then parses the > 
{ string as a command. } 
Val (Command, NewVector ,ErrorPosition); 
IF ErrorPosition = 0 THEN VectorNumber := NewVector 
ELSE 
BEGIN 
Stripwhi te(Command) ; 


{ Show the vector # & address } 
{ Get a command from the user } 
{ If something was typed: >? 


{ Remove leading whitespace } 


Command := ForceCase(Up,Command); { Force to upper case} 
CommandChar := Command[(1]; { Isolate first character } 
CASE CommandChar OF 
'Q' , xe 
tp 


: Quit := True; { Exit VECTORS } 
: DumpTargetData(VectorNumber); { Dump data )} 
: ChangeVector(VectorNumber); { Enter vector } 
: ShowHelp; 
: BEGIN { Zero the vector } 
Vector := NIL; {NIL is 32 zero bits } 
SetIntVec(VectorNumber , Vector); 
DisplayVector(VectorNumber ); 
Writeln('zeroed.'); 
VectorNumber := (VectorNumber + 1) MOD 256 
END; 
Lr : ShowHelp; 
END {CASE} 
END 
END 
{ The following line increments the vector number, rolling over } 
{ to 0 if the number would have exceeded 255: } 
ELSE VectorNumber := (VectorNumber + 1) MOD 256 


UNTIL Quit; 


END. 
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TURBO C 


MOUSE MYSTERIES, 


PART 1: TEXT 


Unraveling 


the mysteries of mouse programming is easy 


with Turbo C and Turbo Paseal. 


Kent Porter 


Mice have moved into the PC main- 
stream. Because of the convenience they 
offer the user, mice have become syn- 
onymous with friendly software and 
intuitive interaction. From the user’s 
perspective, a mouse can seem like a 
simple-to-use, yet mysterious device that is probably 
horrendously complicated to program. From the pro- 
grammer’s viewpoint, however, writing a mouse pro- 
gram is not particularly difficult. In this first part of 
“Mouse Mysteries,” we'll use Turbo C and Turbo Pas- 
cal to explore the text mode region of the software 
world of the mouse. The next article of this two-part 
series will examine the techniques of mouse pro- 
gramming in graphics mode. 

There are relatively few differences between 
mouse functions in Turbo C and Turbo Pascal. In 
the program examples, I’ve purposely called corre- 
sponding mouse functions in each language by the 
same names. Also, I’ve used the same variables and 
algorithms in the demonstration programs wherever 
possible. 
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WHAT YOU WILL NEED 

To incorporate a mouse into the user interface of 

your program, you need three things: 

¢ The hardware mouse itself 

¢ The mouse device driver 

¢ Software mechanisms to communicate with the 
mouse 


The first two items come from the mouse vendor. 
The last item consists of the Turbo C and Turbo 
Pascal programs in Listings | and 2, along with the 
techniques discussed in this article. 

Most mouse vendors adhere to the de facto 
Microsoft standard that governs a two-button mouse, 


or else they furnish a Microsoft-based superset. Of 
the latter, the best known vendor is Logitech, who 
sells a three-button mouse that is compatible with 
the Microsoft standard (except for operations involv- 
ing the third button). 

This series will explore programming the 
Microsoft and Logitech device drivers (and by exten- 
sion, also the great majority of mice by other vendors 
that emulate these mice) with Turbo C. Throughout 
these two articles, we'll also point out the differences 
in mouse programming between Turbo C and Turbo 
Pascal. 


COMMUNICATING WITH THE MOUSE 


The only practical channel of communication 
between the mouse and your software program is 
through the mouse device driver. The driver is 
accessible through software interrupt 33H (51 deci- 
mal), which is not used by DOS. This interrupt is 
claimed by the mouse device driver during load-time 
initialization and thereafter belongs to the driver. 
Parameters are passed to the driver and back to the 
caller through the 8086 registers. 

To call the mouse, you must place a function code 
into register AX and execute interrupt 33H. All the 
mouse Calls use full-word registers, and some calls 
require additional parameters in the registers BX 
through DX. A few mouse calls also expect segment 
addresses in the ES register. Mouse inquiry functions 
return values in the registers BX through DX, wrap- 
ping back to AX if returning four values. Your soft- 
ware can then extract these values as integers, 
assigning and acting on them as appropriate. 


THE MOUSE FUNCTIONS 


Microsoft furnishes 16 mouse functions, numbered (0) 
through 15. Logitech’s mouse functions are the 
same, although a few differ slightly to accommodate 
the third mouse button; there are also two superset 
functions, numbered 16 and 19. The functions from 
both manufacturers are summarized in Table 1. 


continued on page 54 
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Rodent courtesy of Round-Up Pet Center, Scotts Valley, CA 


Bradley Ream 


FUNCTION PURPOSE NATURE 
0 Initialize mouse Control 
1 Show mouse Control 
z Hide mouse cursor Control 
3) Get position and button status Inquiry 
4 Set mouse cursor position Control 
5 Get button press information Inquiry 
6 Get button release information Inquiry 
7 Set minimum/maximum columns (x) Control 
8 Set minimum/maximum rows (y) Control 
9 Define graphics pointer shape (1) Control 
10 Define text pointer shape Control 
ll Read motion counters Inquiry 
12 Define mouse event handler Control 
13 Turn light pen emulation on Control 
14 Turn light pen emulation off Control 
15 Set motion-to-pixel ratio (1) Control 
16 Conditional hide mouse cursor (2) Control 
19 Set speed threshold (2) Control 
NOTES: 


(1) Covered in Part II. 
(2) Logitech only. Not covered here. 


Table 1. The 16 Microsoft Mouse function calls, plus those provided by the 


Logitech mouse. 


MOUSE MYSTERIES 
continued from page 52 


Two sample programs illustrate 
the most important calling/return- 
ing conventions for each of the 
functions listed in Table 1. 
MOUSE.INC (Listing 1) is the 
Turbo C include file that imple- 
ments the mouse function calls. 
MOUSE.PAS (Listing 2) is the 
complementary unit in Turbo 
Pascal 4.0. 

When looking through these 
listings, keep in mind that the 
primary differences between 
the Turbo C and Turbo Pascal li- 
braries relate to the mouse inquiry 
functions, which are mReset, 
mPos, mPressed, mReleased, and 
mMotion. In Turbo Pascal, struc- 
tures to be initialized are owned 
by the calling program and passed 
as variable (VAR) parameters. The 
‘Turbo Pascal mouse functions 
alter the owner’s copy of the struc- 
ture; none of these functions 
returns anything. 

On the other hand, Turbo C 
mouse functions own the struc- 
tures as statics, and return point- 
ers to those structures. This fol- 
lows the spirit of the C language, 
which is much more pointer- 
oriented than Pascal. Also, Pascal 
has no static storage class like that 
in C, 

Therefore, when writing Turbo 
C programs that incorporate the 
mouse, be sure to declare pointer 
variables for the structures that 
you intend to use, and to initialize 


54 TURBO TECHNIX May/June 1988 


those variables with the inquiry 
functions’ returned values. 
Function 0: Initializing the mouse 
(mReset). Any program that uses 
the mouse must initialize it during 
the setup phase by calling func- 
tion 0). Failure to do so means that 
your program inherits a garbage 
mouse status from either powerup 
or the previous program, which- 
ever is most recent. 

The reset function clears the 
previous mouse status, places the 
mouse cursor in the center of the 
screen (though the cursor is invisi- 
ble—see the discussion of func- 
tions | and 2 below), and sets the 
scope of operation to the full dis- 
play. Upon returning, AX contains 
the mouse status (0 if the mouse 
device driver is not installed, non- 
zero if it is installed), and BX con- 
tains the number of mouse but- 
tons (2 for Microsoft and clones, 3 
for Logitech). 

In Turbo Pascal, it’s convenient 
to stuff the returned values into a 
record, which is why the unit in 
Listing 2 defines the resetRec 
type. Because this definition is in 
the interface part of the mouse 
unit, a program that USES this 
unit can declare resetRec vari- 
ables as though the type were 
intrinsic. 

Note that the mReset procedure 
receives the resetRec variable as a 
VAR parameter. In other words, it 
jointly owns the record with the 
caller, thus enabling the proce- 
dure to pass back the values 
returned by the mouse device 


driver. The Pascal equivalents to 
inquiry functions 3, 5, 6, and 11 
operate similarly on records 
passed as VAR parameters in 

to return results. Let’s declare the 
resetRec variable as follows: 


Var 
theMouse : resetRec; 


We then initialize the mouse with 
this call: 


mReset (theMouse); 


Afterwards, our program can 
check to see if a mouse is present 
by using a test such as: 

if theMouse.exists then 

{do mouse stuff} 
else 

{mouse isn’t active} 

Things are a little different in 
Turbo C, where we declare point- 
ers to the resetRec structure. In 
Pascal, the call to initialize the 
mouse is: 


mReset (theMouse); 


However, in Turbo C, the mouse 
initialization call is: 


theMouse = mReset (); 


Both calls do the same thing, but 
the calling sequence is different 
because of the use of pointers 

in C. 

It’s advisable to call mReset 
again at the end of the program. 
This step restores the device 
driver to its default state and de- 
activates the mouse, so that subse- 
quent programs don’t inherit an 
unwanted mouse status. 


Function 1: Show mouse cursor 
(mShow). mReset leaves the 
mouse cursor off. Therefore, the 
very next step is usually to turn 
the mouse cursor on. The only 
way to do so is via function 1, 
mShow. This control function 
doesn’t return a value, nor does 
its counterpart, mReset. 


Function 2: Hide mouse cursor 
(mHide). This function turns off 
the mouse cursor without other- 
wise changing its status. Even 
though the cursor is “hidden” 
after a call to function 2 (via 
mHide), it still moves in response 
to physical travel of the mouse; of 
course, you’re not aware of the 
cursor’s movement until you call 
mShow again and discover it in a 
different place. 

A strange tension exists among 
functions 0, 1, and 2—they all 


control an internal value called 
the cursor flag, which is a signed 
integer. mReset (function () sets 
the flag to -1, making the cursor 
invisible. mShow (function 1) 
increments the flag to 0, which 
tells the device driver that the cur- 
sor should be visible. mHide 
(function 2) decrements the flag 
back to -1. The net result is that if 
you reset the mouse and then call 
mHide, it takes two calls to mShow 
to make the cursor visible, since 
the internal flag has dropped 

to -2. 

Oddly, the mouse device driver 
doesn’t furnish an inquiry to 
determine the value of the inter- 
nal cursor flag, so the program 
cannot ask if the cursor is on or 
off. Therefore, the programmer is 
responsible for tracking the 
mouse cursor’s status. 


Function 3: Get position and but- 
ton status (mPos). This inquiry 
function returns information 
about the status of the mouse; spe- 
cifically, it tells the location of the 
cursor and whether any button is 
pressed down. All information is 
reported in real time—in other 
words, if the mouse is in motion, 
you get a current position report 
(which is probably not the 
mouse’s destination). Likewise, 
making infrequent calls to this 
function can potentially cause a 
button click to be missed. To cap- 
ture a click as well as the mouse’s 
position at the ultimate destina- 
tion, use function 12 (see func- 
tions 5 and 6 for more button 
information). Function 3 is chiefly 
useful in graphics—within a tight 
loop, this function can write a 
pixel to draw a track based on 
mouse movement, transforming 
the mouse into a pencil of sorts. 
Another common use for function 
3 is to determine the location of 
the cursor. Determining the cur- 
sor’s position can come in handy 
if you intend to jump it to another 
place and you need an address to 
which you'll return the cursor 
later. 

Function 3 returns the button 
status in BX, the column in CX, 
and the row in DX. With a two- 
button mouse, bits 0 and | in BX 
are set if the left and right but- 
tons, respectively, are down. Bit 2 
represents the center button in 
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LISTING 1: MOUSE. INC 


/* MOUSE.INC: Turbo C Source code for mouse interface functions. 
fe Must #include dos.h before this #include to define the 
/* register set used to pass args to device driver 


/* we a ee en ee ee ee eee ee eee 


/* Define int for mouse device driver */ 


#define callMDD int86(0x33, &inreg, 


/* Define sorting macros used locally */ 


#define lower (x, y) 
#define upper (x, y) 


OOS YT 2k 2 
Che YD PIC8 


/* STATIC REGISTERS USED THROUGHOUT */ 


union REGS inreg, outreg; 


/* STRUCTURES USED BY THESE FUNCTIONS */ 


typedef struct { 
int exists, 
nButtons; 
} resetRec; 


typedef struct { 
int buttonStatus, 
opCount, 
column, row; 
} locRec; 


typedef struct { 
int hCount, 
vCount; 
} moveRec; 
/* ew eww wwe eee ee wee eww meee eee eee ees 


/* Following are implementations of the Microsoft mouse functions */ 


resetRec *mReset () 


/* Resets mouse to default state. Returns pointer to a structure */ 
/* indicating whether or not mouse is installed and, if so, how ef 


/* many buttons it has. 


/* Always call this function during program initialization. af 


< 
static resetRec m; 


inreg.x.ax = 0; 


callMDD; 
m.exists = outreg.x.ax; 
m.nButtons = outreg.x.bx; 
return ( &m ); 

BO ek ee 


void mShow (void) 


/* Makes the mouse cursor visible. Don't call if cursor is already */ 


/* visible, and alternate with calls 
{ 

inreg.x.ax = 1; 

cal MDD; 
oa be 
void mHide (void) 


/* Makes mouse cursor invisible. Movement and button activity are */ 
/* still tracked. Do not call if cursor is already hidden, and “yf 


/* alternate with calls to mShow 
€ 

inreg.x.ax = 2; 

cal lMDD; 
a 
locRec *mPos (void) 


/* Gets mouse cursor position and button status, returns pointer */ 


/* to structure containing this info 
€ 
static locRec m; 


inreg.x.ax = 3; 
cal lMDD; 


/* bits 0-2 on if corresp button is down */ 
/* # times button has been clicked */ 


/* returned by mPos, mPressed, mReleased */ 


&outreg) 


y 
y 


/* TRUE if mouse is present */ 
/* # of buttons on mouse */ 
/* returned by mReset */ 


/* position */ 


/* net horizontal movement */ 
/* net vertical movement */ 
/* returned by mMotion */ 


/* function 0 */ 


to mHide. */ 


/* function 1 */ 


/* function 2 */ 


/* function 3 */ 
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/* button status */ 
/* horiz position */ 
/* vert position */ 


m.buttonStatus = outreg.x.bx; 
m.column = outreg.x.cx; 
m.row = outreg.x.dx; 
return (&m); 
BP PARISI SS Oe Se “/ 
void mMoveto (int newCol, int newRow) 
/* Move mouse cursor to new position */ 


€ 
inreg.x.ax = 4; /* function 4 */ 
inreg.x.cx = newCol; 
inreg.x.dx = newRow; 
cal (MDD; 
AR Sess ree riers a << reemn a= af 


locRec *mPressed (int button) 

/* Gets pressed info about named button: current status (up/down), */ 
/* times pressed since last call, position at most recent press. */ 
/* Resets count and position info. Button 0 is left, 1 is right on */ 


/* Microsoft mouse. il A 
/* Returns painter to locRec structure containing info. eh 
€ 
Static locRec m; 
inreg.x.ax = 5; /* function 5 */ 
inreg.x.bx = button; /* request for specific button */ 
cal lMDD; 


m.buttonStatus = outreg.x.ax; 
m.opCount = outreg.x.bx; 
m.column = outreg.x.cx; 
m.row = outreg.x.dx; 
return (&m); 
Dp US Oe SSRIS Ce “/ 
locRec *mReleased (int button) 
/* Same as mPressed, except gets released info about button */ 
{ 
static locRec m; 


/* function 6 */ 


inreg.x.ax = 6; 
= /* request for specific button */ 


inreg.x.bx = button; 

cal lMDD; 

m.buttonStatus = outreg.x.ax; 
m.opCount = outreg.x.bx; 


m.column = outreg.x.cx; 
m.row = outreg.x.dx; 
return (&m); 

BOY (bad eR INN BN has a RT It Sf 


void mColRange (int hmin, int hmax) 
/* Sets min and max horizontal range for mouse cursor. Moves */ 
/* cursor inside range if outside when called. Swaps values if */ 


/* hmin and hmax are reversed. Li 
1 
inreg.x.ax = 7; /* function 7 */ 
inreg.x.cx = hmin; 
inreg.x.dx = hmax; 
cal lMDD; 
BUI TC ine */ 


void mRowRange (int vmin, int vmax) 
/* Same as mHminmax, except sets vertical boundaries. */ 
{ 


inreg.x.ax = 8; /* function 8 */ 
inreg.x.cx = vmin; 
inreg.x.dx = vmax; 
cal lMDD; 
PE I if 


void mGraphCursor (int hHot, int vHot, unsigned maskSeg, 
unsigned maskOfs) 

/* Sets graphic cursor shape */ 

€ 

struct SREGS seg; 


inreg.x.ax = 9; /* function 9 */ 
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the Logitech mouse and other 
three-button mice. A zero in any 
of these bit positions means the 
corresponding button is not cur- 
rently being pressed. 


Function 4: Set mouse cursor 
position (mMoveto). This function 
moves the cursor directly to the 
specified column and row. The 
mouse device driver is sensitive to 
the display adapter in use, but 
handles positioning coordinates 
differently than you might expect. 
Even in text mode, the device 
driver regards the screen as a 640 X 
200-pixel array (which is the same 
as the CGA high-resolution graph- 
ics mode). Under this scheme, a 
character cell is 8 X 8 pixels for 
the normal 80 X 25 text display. 

The mouse cursor position in 
text mode is always the pixel 
address of the upper left corner of 
the current character cell. Thus, 
home position is 0,0; the position 
of the next cell to the right is 8,0; 
the cell directly below that is 
located at 8,8; and so forth. To cal- 
culate the mouse cursor position, 
multiply the text column and row 
coordinates by eight. For instance, 
the approximate center of the text 
screen is the pixel address of 
39,12; this maps to 312,96 in 
mouse cursor coordinates. To 
translate in the reverse direction, 
divide the mouse cursor coordi- 
nates by eight. 

In graphics mode, the cursor 
moves smoothly, pixel by pixel. In 
text mode, however, it jumps from 
cell to cell in order to avoid oc- 
cupying two or more cells at the 
same time. If you pass coordinates 
to mMoveto that are not multiples 
of eight (e.g., 313,97), the device 
driver ignores the remainders and 
positions the cursor at the next 
lower integral text cell (312,96). 


Function 5: Button press informa- 
tion (mPressed). The mouse 
device driver records how many 
times each button is pressed. 
mPressed calls function 5 to get 
this information for any specific 
button. The button numbers are: 
0 = Left; 1 = Right; for three- 
button mice only, 2 = Middle. 

A request for press information 
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about a specific button clears its 
history. Thus, a call might reveal 
that button | has been pressed 
twice. The next time you ask 
mPressed about button 1, it re- 
turns zero if the button was not 
pressed since that earlier call. 

This function also returns the 
button status, which is real-time 
information about all buttons 
(exactly as in mPos). Additionally, 
function 5 provides the column 
and row of the cursor’s position 
during the last time the button of 
interest was pressed. If the button 
is currently down (the status bit is 
ON), the position report is the 
current location; otherwise, the 
position report is historical 
information. 

mPressed is of limited useful- 
ness—if it’s called from within a 
loop, the loop might iterate many 
times while the user has the but- 
ton pressed down. Each time, 
mPressed reports the same button 
operation as though it were a new 
event. mReleased (described 
below) is a better choice, since it 
waits to update the internal coun- 
ter until the user has released the 
button. 


Function 6: Get button released 
information (mReleased). This 
function is similar to mPressed, 
except that it reports how many 
times the button of interest has 
been released after being pressed. 
It’s a more reliable indicator of 
a given button’s activity than is 
mPressed, simply because a 
release is a singular event that 
isn’t tricked by a button’s current 
status. 


Functions 7 and 8: Set Min/Max 
columns and rows (mColRange 
and mRowRange). These two 
functions limit the operational 
area of the mouse cursor, much 
like fencing the backyard to con- 
fine the dog. Function 7 
(mColRange) governs the range 
of columns, and function 8 
(mRowRange) controls the rows 
in which the cursor can appear. 
When these two functions are 
invoked, the cursor—if previously 
located outside the defined area— 
moves inside of it. Thereafter, the 
cursor simply refuses to cooperate 
if you try moving it beyond any 
boundary. 

The default condition gives the 
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> 

vo 
/* 
/* 
/* 
/* 
/* 
€ 


inreg.x.bx = hHot; /* cursor hot spot: horizontal */ 
inreg.x.cx = vHot; /* cursor hot spot: vertical */ 
inreg.x.dx = maskOfs; 
seg.es = maskSeg; 
int86x (0x33, &inreg, &outreg, &seg); 
/* acwccwoceesasasewnoceanae */ 
id mTextCursor (int curstype, unsigned arg1, unsigned arg2) 
Sets text cursor type, where 0 = software and 1 = hardware) ball f 
For software cursor, arg1 and arg2 are the screen and cursor wy 
masks. */ 
For hardware cursor, arg1 and arg2 specify scan line start/stop */ 
i.e. cursor shape. */ 


inreg.x.ax = 10; /* function 10 */ 
inreg.x.bx = curstype; 
inreg.x.cx = argl; 
inreg.x.dx = arg2; 
cal lMDD; 
Bp EA EOS OEE st 
moveRec *mMotion (void) 


/* Reports net motion of cursor since last call to this function */ 
{ 
static moveRec Mm; 
inreg.x.ax = 11; /* function 11 */ 
cal lMDD; 
m.hCount = _CX; /* net horizontal */ 
m.vCount = _DX; /* net vertical */ 
return (&m); 
Bg fd 20 OC OE OSI Lf 
void mInstTask (unsigned mask, unsigned taskSeg, unsigned taskOfs) 
/* Installs a user-defined task to be executed upon one or more */ 
/* mouse events specified by mask. a/ 
{ 
struct SREGS seg; 
inreg.x.ax = 12; /* function 12 */ 
inreg.x.cx = mask; 
inreg.x.dx = taskOfs; 
seg.es = taskSeg; 
int86x (0x33, &inreg, &outreg, &seg); 
1 fe fC SECO IE TT xf 
void mlpenOn (void) 
/* Turns on light pen emulation. This is the default condition. «/ 
{ 
inreg.x.ax = 13; /* function 13 */ 
cal lMDD; 
DT id BIO A EI IN II IS i / 
void mlpenoff (void) 
/* Turns off light pen emulation. */ 
{ 
inreg.x.ax = 14; /* function 14 */ 
cal lMDD; 
1S IO ISS LES Rtas ef 
void matio (int horiz, int vert) 
/* Sets mickey-to-pixel ratio, where ratio is R/8. Default is 16 */ 
/* for vertical, 8 for horizontal */ 
{ 
inreg.x.ax = 15; /* function 15 */ 
inreg.x.cx = horiz; 
inreg.x.dx = vert; 
cal lMDD; 
/* SdsmasSecseaceeeoccesceue */ 
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LISTING 2: MOUSE.PAS 


Unit mouse; 


{ For Turbo Pascal Release 4.n. Won't work with older levels 
{ Implements calls to mouse device driver. Works with the 
{ Logitech and Microsoft mice, and anything else compatible. 


vi 
{ NOTE!!! 
c COMPILER OPTIONS MUST BE SET TO FORCE FAR CALLS! 
{ If not, user defined task installed by mInstTask 
€ will crash the system. 
{ ee 
Interface 
{3U \tp} 
Uses DOS; { For interrupts and registers 
Const 
MDD = $33; { Interrupt for mouse device driver 
Type 


resetRec = record 
exists : 
nButtons : 


End; 


locRec = record 


Boolean; 
integer; 


{ Initialized by mouse function 0 
{ TRUE if mouse is present 
{ # buttons on mouse 


{ Initialized by mouse fcns 3, 5, and 6 
{ bits 0-2 on if corresp button is down 
{ # times button has been clicked 


{ opCount not returned by fen 3 
{ position 


AAA 


function 
function 
function 
function 
function 


function 


function 
function 
function 


function 
function 
function 


function 
function 
function 
function 


{ Initialized by mouse fcn 11 
{ net horizontal movement 
{ net vertical movement 


FWN oO 


vi 


buttonStatus, 
opCount, 
column, 
row : integer; 
End; 
moveRec = record 
hCount, 
vCount : integer; 
End; 
Var Reg : Registers; 
{ These are the Microsoft mouse functions } 
Procedure mReset (var mouse : resetRec); 
Procedure mShow; 
Procedure mHide; 
Procedure mPos (var mouse : locRec); 
Procedure mMoveto (col, row : integer); 
Procedure mPressed (button : integer; 
var mouse : locRec); 
Procedure mReleased (button : integer; 
var mouse : locRec); 
Procedure mColRange (min, max : integer); 
Procedure mRowRange (min, max : integer); 
Procedure mGraphCursor (hHot, vHot : integer; 
maskSeg, maskOfs : word); 
Procedure mTextCursor (ctype, p1, p2 : word); 
Procedure mMotion (var moved : moveRec); 
Procedure mInstTask (mask, 
taskSeg, taskOfs : word); 
Procedure mLpenOn; 
Procedure mLpenoff; 
Procedure mRatio (horiz, vert : integer); 
{ ee 


ain ctllien lin cali cil ctllien atin cilia tin al 
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cursor access to the entire display 
area; these procedures override 
the default. A typical application is 
to limit the cursor to a pop-up dia- 
log box. To do so, follow these 
steps: 


1. Get the current cursor position 
with mPos. 


2. Create the pop-up. 


3. Set the boundaries with 
mColRange and mRowRange. 


4. Perform the operations neces- 
sary to make the pop-up go 
away. 


5. Restore full-screen mouse oper- 
ation with another set of calls to 
these procedures, this time 
passing the absolute boundaries 
of the display as parameters. 


6. Use mMoveto with the cursor 
position saved in step | to put 
the cursor back where it was 
during step 1. Note that both 
procedures sort the parameters 
to make sure that they’re in cor- 
rect order. 


Function 10: Set text cursor 
(mTextCursor). You have your 
choice of two text cursors when 
using a mouse; function 10 lets 
you select a cursor and specify 
how it will appear. The hardware 
cursor selection (option 1) puts 
the video adapter’s text cursor 
under control of the mouse, pro- 
viding a single cursor on the dis- 
play (although the text I/O posi- 
tion does not move with the 
mouse; see the discussion of 
MOUSDEMO later in this article). 
The software cursor (curstype = 0 
in Listing 1, or ctype = 0 in List- 
ing 2) lets you have two cursors on 
the display at the same time. One 
cursor operates normally in 
response to I/O, while the other 
cursor is controlled by the mouse. 
To reduce user confusion, the 
software mouse cursor can have a 
unique appearance provided by 
any of the 256 text characters. My 
favorite is character 18H, which is 
an upward-pointing arrow. 

The software cursor is the 
default. Thus, if you call mReset 
and then mshow without an inter- 
vening call to function 10, you get 
a mouse cursor independent of 
the normal hardware cursor. 
Furthermore, this default software 
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cursor is a simple full-cell block 
that inverts the attributes of any 
character cell it occupies. For 
example, if you have gray letters 
on a black background, the cell 
occupied by the software mouse 
cursor contains a black letter on a 
gray background. Unlike the hard- 
ware cursor, the software cursor 
does not blink. 

To change the software cursor’s 
attributes, pass two masks in the 
CX and DX registers (in Listing 1, 
use arguments argl and arg2, 
respectively; in Listing 2, use 
parameters pl and p2, respec- 
tively). arg] is the screen mask; it 
should have the value 77FFH if 
the cursor is a see-through rectan- 
gle, and 0000H if the cursor uses 
one of the 256 characters as its 
shape. arg2 defines the cursor 
itself. Place a foreground/back- 
ground attribute byte in the upper 
eight bits, and place the ASCII 
value of the cursor shape (charac- 
ter) in the lower eight; use ASCII 
character 0 if the cursor is to be a 
simple rectangle. For example, the 
patterns for a see-through block 
cursor are 77FFH and 7700H; the 
patterns for a gray up-arrow cur- 
sor against a black background 
are 0000H and 0718H (where 18H 
is the arrow symbol). Complete 
the parameter setup by passing (0) 
as the curstype argument. 

A hardware cursor is simpler to 
define. Set up arg] and arg2 with 
the starting and ending scan lines 
of the cursor. The top scan line is 
always 0). On a monochrome 
adapter, the bottom scan line is 
12. For all graphics boards operat- 
ing in text mode, the bottom scan 
line is 7 (just as it is for ROM 
BIOS interrupt 10H, function 1). 
To tell the mouse device driver to 
take control of the hardware cur- 
sor, pass the value 1 as the 
curstype parameter. 


MICE AT WORK 


The MOUSDEMO program 
(MOUSDEMO.C in Listing 3 and 
MOUSDEMO.PAS in Listing 4) 
has two phases. The first phase 
demonstrates the software cursor, 
which is an up-arrow that travels 
one cell at a time around the text 
display in response to mouse 
movement. When the software 
cursor moves into a cell already 
occupied by a character, the cur- 
continued on page 60 


IMPLEMENTATION 
Function lower (n1, n2 : integer) : { Local to unit} 
Begin 
If ni < n2 then lower := n1 
Else lower := n2; 
End; 


integer; 


Function upper (n1, n2 : integer) : integer; { Local to unit } 
Begin 

If n1 > n2 then upper := n1 
Else upper := n2; 


End; 

(pe teen eens R cia sicie asso y 

Procedure mReset; { Resets mouse to default condition } 
Begin 


reg.ax := 0; 
intr (MDD, reg); 
if reg.ax <> 0 then 
mouse.exists := TRUE 
else 
mouse.exists 
mouse.nBut tons 
End; 
(ERS GE CIO ICI a 
Procedure mShow; 
Begin 
reg.ax := 1; 
intr (MDD, reg); 
End; 


{ Make mouse cursor visible } 


Procedure mHide; 
Begin 
reg.ax := 2; 
intr (MDD, reg); 
End; 


{ Make mouse cursor invisible } 


Procedure mPos; { Get mouse status and position } 
Begin 

reg.ax := 3; 

intr (MDD, reg); 

mouse.buttonStatus := reg.bx; 

mouse.column := reg.cx; 


mouse.row := reg.dx; 


End; 
A ya Rena ae aaa iO sis wine at B 
Procedure mMoveto; { Move mouse cursor to new location } 
Begin 
reg.ax := 4; 
reg.cx := col; 
reg.dx := row; 
intr (MDD, reg); 
End; 
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Procedure mPressed; { Get pressed info about a given button } 


Begin 
reg.ax := 5; 
reg.bx := button; 
intr (MDD, reg); 
mouse.buttonStatus := reg.ax; 
mouse.opCount := reg.bx; 
mouse.column := reg.cx; 
mouse.row := reg.dx; 


End; 
5 ET EE RE ERS IO > 
Procedure mReleased; { Get 
Begin 

reg.ax := 6; 

reg.bx := button; 


intr (MDD, reg); 
mouse.buttonStatus := reg.ax; 
mouse.opCount := reg.bx; 
mouse.column := reg.cx; 
mouse.row := reg.dx; 

End; 

Casas Sen's neces sas o cee as =e > 

Procedure mColRange; 

Begin 
reg.ax := 7; 
reg.cx := lower (min, max); 
reg.dx := upper (min, max); 
intr (MOD, reg); 


Procedure mRowRange; 

Begin 
reg.ax := 8; 
reg.cx := lower (min, max); 
reg.dx := upper (min, max); 
intr (MDD, reg); 


End; 
OI hI Sore TC > 
Procedure mGraphCursor; 
Begin 
reg.ax := 9; 
reg.bx := hHot; 
reg.cx := vHot; 
reg.dx := maskOfs; 


reg.es := maskSeg; 
intr (MDD, reg); 
End; 


[2 ee eee eee 
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released into about a button } 


{ Set column range for mouse } 


{ Set row range for mouse } 


{ Set mouse graphics cursor } 


MOUSE MYSTERIES 
continued from page 59 


sor temporarily replaces the text. 
When the cursor moves on, the 
text reappears. 

The software cursor phase 
works like this: As you move the 
cursor around with the mouse, 
notice that a mouse position 
report appears on the display 
each time that you click the left 
button. There are two cursors on 
the screen: the normal flashing 
underscore (which is the hard- 
ware cursor) and the up-arrow 
cursor controlled by the mouse. 

This condition continues under 
control of the first Turbo C DO 
loop (REPEAT..UNTIL in the 
Turbo Pascal program) until you 
click the right mouse button. At 
that point, the demo moves into 
the second phase to illustrate the 
hardware cursor. 

The hardware cursor comes 
under control of the mouse as a 
result of the second call to 
mTextCursor, which sets the cur- 
sor shape to a small block the size 
of a character. 

In this part of the demo, move 
the mouse cursor and click the 
right button to signal that you 
want to enter text, then begin typ- 
ing after the program prints a 
question mark. End the input by 
pressing Enter, then move the cur- 
sor elsewhere and repeat. You can 
end the program by clicking the 
right button. 

Even though the mouse takes 
over the hardware cursor’s shape 
and position, it does not affect the 
location of normal I/O opera- 
tions. Thus, regardless of the 
physical cursor’s location on the 
display, an input or output pro- 
ceeds from wherever the last I/O 
occurred. This is admittedly 
strange, but true. 

Therefore, if you want the I/O 
location to correspond to the posi- 
tion of the mouse-controlled cur- 
sor, you have to track the cursor. 
In Turbo Pascal, use GotoXY 
as shown in the second 
REPEAT..UNTIL loop of 
MOUSDEMO.PAS. This process 
involves converting the mouse 
position into normal text coordi- 
nates through integer division by 
eight. 

Note that MOUSDEMO.C has a 
couple of local functions—celrSer 


and gotoxy—to emulate intrinsic 
Pascal procedures. Both of these 
functions call ROM BIOS inter- 
rupt 10H, which furnishes video 
services. The clrScr function 
merely resets the display to the 
current video mode, causing the 
adapter to clear the screen. The 
gotoxy function calls ROM BIOS 
function 2, which repositions the 
cursor to the specified row and 
column. While these functions 
have nothing to do with the 
mouse, they’re useful additions 
to your Turbo C bag of tricks. 

Similarly, the mMoveto after the 
gets in MOUSDEMO.C (ReadIn in 
MOUSDEMO.PAS) is necessary to 
relocate the mouse cursor back to 
the beginning of the output string. 
Otherwise, the cursor remains sta- 
tionary at the end of the output 
string until you move the mouse 
again, at which point the cursor 
jumps back to the start of the 
string and commences motion 
from that position. 

Note that this clean-up process 
resets the mouse cursor. This is 
in deference to subsequent pro- 
grams, including DOS, which 
might otherwise be peculiarly 
affected if the mouse is still 
“alive.” 

The MOUSDEMO program is 
highly mouse-intensive. It expends a 
great deal of programmatic energy 
to get information about the 
mouse, even though a mouse is an 
accessory and not the principal 
input device for most software. 
For example, a menu-driven appli- 
cation might accept several alter- 
native forms of input for selecting 
a menu choice: 


® Cursor keys followed by Enter 

© An alphabetic key identifying a 
choice 

® Mouse movement and a click 


The introduction of a mouse, 
with all of the attendant inquiry 
and control calls, greatly compli- 
cates this situation. Life would be 
much easier if we could simply 
check periodically to see if the 
user has done something with the 
mouse, and if so, act upon it. For- 
tunately, mouse function 12 lets us 
do precisely that. 

continued on page 62 


Procedure mTextCursor; 


NOTES: 
Type 0 


{ Set mouse text cursor } 


> 


is the software cursor. When specified, p1 } 


and cursor masks. > 


Type 1 is the hardware cursor. When specified, p1 } 
and p2 are the start and stop scan lines, i.e. } 


{ 
{ 
{ and p2 are the screen 
{ 
x 
{ 


the cursor shape. 


5 
o 
a 
. 
z 
as ee ee oe 


reg.dx 
intr (MDD, 
End; 
{ www ewww wee eee wee wesw eee ewe 
Procedure mMotion; 


Begin 
reg.ax := 11; 
intr (MDD, reg); 
moved.hCount := reg.cx; 


moved.vCount := reg.dx; 
End; 
{ wem eee weer wee eee ees esceeces 
Procedure mInstTask; 
Begin 
reg.ax := 12; 
reg.cx := mask; 
reg.dx := taskOfs; 
reg.es := taskSeg; 
intr (MDD, reg); 
End; 
{ ee 
Procedure mLpenOn; 
Begin 
reg.ax := 14; 
intr (MDD, reg); 
End; 
{ ewe eee eeeeeeseseeeecccecccs 
Procedure mLpenOff; 
Begin 
reg.ax := 15; 
intr (MDD, reg); 
End; 
{ wee wee ee m eee eee eee we ee eeeee 


Procedure mRatio; 


{ NOTES: 
{ Ratios are R/8. 


{ Default is 16 for vertical, 8 for horizontal 


Begin 
reg.ax := 15; 
reg.cx := horiz; 
reg.dx := vert; 
End; 
{ wee ewe ee eeeeeeeceeecsecccs 
End. 


} 


{ Net movement of mouse since last call } 


{ Expressed in mickeys (1/100") } 


{ Install user-defined task } 


{ Turn on light pen emulation (default) } 


{ Turn off light pen emulation } 


> 
{ Set mickey to pixel ratio } 
sy 
a; 
> 
> 
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LISTING 3: MOUSDEMO.C 


/* MOUSDEMO.C: Demo of basic mouse operations */ 
/* INCLUDES */ 

#include <stdio.h> 

#include <dos.h> 

#include <mouse. i> 


/* CONSTANTS */ 

#defime HARDWARE 1 

#define SOFTWARE 0O 

#define LEFT 0 

#define RITE 1 

#define ROMBIOS int86 (0x10, &inreg, &outreg) 


/* cursor types 
/* mouse buttons 

/* BIOS calls 
/* LOCAL FUNCTIONS */ 


void clrScr (void); 
void gotoxy (int col, int row); 


/* see weeesesseeeseewecees ese se eweeces cece eee eee ennceeaseceaseces 
main () 

.é 

resetRec *theMouse; /* from reset function 
lLocRec *its: /* from mouse inquiries 
int col, row; 

char input [80]; 


/* clear screen 
/* reset mouse 
/* do following if it exists 


clrScr (); 
theMouse = mReset (); 
if (theMouse->exists) ¢ 


/* Software mouse cursor */ 
puts ("Software cursor:"); 


2y, 
oe 
*/ 


printf ("Demo of a mouse with %d buttons\n", theMouse->nButtons); 


puts ("Move the mouse around and click the left button"); 
puts ("Click the right button for hardware demo\n"); 
mTextCursor (SOFTWARE, 0x0000, 0x0718); /* set s/w cursor 
mShow (); /* turn it on 
do { 
its = mReleased (LEFT); 
if Cits->opCount > 0) ¢ 
mHide (); /* cursor off in case of scroll 
printf ("\nMouse is at col %d, row %d", its->colum, 
its->row); /* position report 
mShow (); /* cursor back on 
> 
its = mReleased (RITE); 
} while (its->opCount == 0); 


/* check left button 


/* check right button 
/* repeat until operated 


/* Now do hardware mouse cursor demo */ 
clrser, ()s 
puts ("Hardware cursor:"); 
puts ("Move the mouse, click left button"); 
puts ("Type something and press Enter"); 
puts ("Click right button to end demo"); 
theMouse = mReset (); 


/* clear screen 


/* reset mouse 


mTextCursor (HARDWARE, 2, 5); /* set h/w cursor 
mShow (); /* cursor on 
do { 


its = mReleased (LEFT); 

if (its->opCount > 0) ¢ 
col = its->column / 8; 
row = its->row / 8; 
gotoxy (col, row); 
putchar ('?'); 
gets (input); 
mMoveto (its->column, its->row); 

} 

its = mReleased (RITE); 

} while (its->opCount == 0); 


/* check left button 
/* if operated... 
/* compute text position 


/* go there 
/* prompt 


/* restore position 


/* check right button 
/* repeat until operated 


yf 
tj 


i! 
+f 
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Function 12: Define mouse event 
handler (mInstTask). This rather 
esoteric function keeps the code 
free of frequent mouse checks. In 
fact, function 12 is so powerful 
that you can incorporate a mouse 
into your program with very few 
function calls. 

mInstTask (see Listings 1 and 2) 
attaches a user-defined routine (a 
“task”) to the mouse device driver. 
When calling mInstTask, you 
effectively tell the device driver, 
“Watch for certain events. When 
they happen, call my routine.” 
Thus, a portion of your program 
becomes an extension of the 
device driver. 


THE EVENT HANDLER 


An event is any of the mouse 
actions listed below. You pass a 16- 
bit mask in the CX register to tell 
the device driver which events to 
watch for. The bit numbers and 
their corresponding events are 
given in Table 2. For example, if 
you want the device driver to call 
your routine when either the left 
or right button is released, pass 
the mask 0014H. Note that bits 7 
through 15 are unused. 


BIT EVENT 

0 Mouse cursor moved 

1 Left button pressed 

2 Left button released 

3 Right button pressed 

4 Right button released 

5 Middle button pressed 
(Logitech only) 

6 Middle button released 


(Logitech only) 


Table 2. Mouse events and their cor- 
responding mask bits. 


You must also give the address 
of your event handler routine to 
the task installer. Pass the address’ 
segment as the second parameter 
and its offset as the third parame- 
ter, as in the example below: 
mInstTask(0X14,seg(handler), 

ofs(handler)); 

Thereafter, whenever the left or 
right button is released, the device 
driver automatically hands control 
to your routine via a far call. 

When calling your handler, the 
device driver passes the informa- 
tion to the registers summarized 


in Table 3. You can examine these 
registers to find out which event 
occurred and where it occurred. 
I'll cover this process presently, 
but first let’s look at how to write 
the event handler. 


REGISTER DATA 
AX Event that occured 
(a bit set as above) 
BX Status of the buttons 
(1 bit if down) 
CX Horizontal cursor postion 
DX Vertical cursor position 


Table 3. Returning data from mouse 
events. 


Everything about your mouse 
event handler is the same as an 
interrupt service routine except 
that the event handler must exit 
via a far return. In Turbo Pascal, 
you must exit via a RETF instruc- 
tion, rather than with the IRET 
instruction that Turbo Pascal auto- 
matically inserts into the machine 
code before the END of a proce- 
dure identified as INTERRUPT. 
As a result, you have to code the 
entire 12-byte exit processing 
sequence with inline code, as 
shown in MOUSEVNT-PAS (List- 
ing 5). This code, by the way, is 
invariant for any mouse event 
handler, so you can safely insert it 
“as is” into your own routines. 

The most important restriction 
on an interrupt service routine is 
that it cannot perform any I/O, 
DOS, or ROM BIOS calls. Since 
it’s seemingly cut off from the 
world, what can the event handler 
possibly do? The answer is, “Not 
much”—nor should it. The object 
of the game is to handle the event 
as quickly as possible and return, 
so that the device driver can 
release control and let the run- 
ning program resume. Conse- 
quently, the event handler should 
confine itself to saving a record of 
the event that the program can 
process at its convenience. 


DOING IT IN TURBO 
PASCAL 4.0 

Turbo Pascal 4.0 interrupt proce- 
dures have access to global 
variables due to the compiler- 
inserted entry processing (which 


continued on page 64 


/* Clean up and end of job */ 


mTextCursor (HARDWARE, 6, 7); /* use 11, 12 if mono board 


mReset (); /* reset cursor 
clrser ¢)- /* clear screen 
> else 
puts ("Mouse not present in system. Demo can't run."); 
Pe Seka renee cea me cal 
void clrScr (void) /* clears the screen 
/* Uses ROM BIOS int 10h to reset video mode to itself 
{ 
struct REGS inreg, outreg; 
inreg.h.ah = OxOF; /* first get current mode 
ROMBIOS; 
inreg.h.al = outreg.h.al; /* copy mode 
inreg.h.ah = 0; /* now reset to same mode 
ROMBIOS; 
ee = 2 wien min ania ein er mim = */ 


void gotoxy (int col, int row) /* position text cursor 


/* Uses ROM BIOS int 10h 


{ 
struct REGS 


inreg, outreg; 
inreg.h.ah = 2; /* function 2 sets cursor pos 
inreg.h.bh = 0; /* video page 0 is active 
inreg.h.dh = row; 
inreg.h.dl = col; 
ROMBIOS; 
Da fad ee Ne oI I A RI I */ 


LISTING 4: MOUSDEMO.PAS 


PROGRAM mousdemo; { Demo of the mouse unit } 


USES dos, crt, mouse; 
CONST hardware = 1; { cursor types 
software = 0; 
left = 0; { mouse buttons 
right LR 
VAR theMouse : resetRec; { for mouse fcn 0 
its : locRec; { for mouse inquiries 
col, row : integer; 
input : string [80]; 
BEGIN 
CLRSCR; { clear the screen 


mReset (theMouse); 
IF theMouse.exists THEN 


{ initialize the mouse 
{ and make sure we have one 


{ Do the software mouse demo first } 
BEGIN 
WRITELN ('Software cursor:'); 
WRITELN ('Demo of a mouse with ', 
theMouse.nButtons, ' buttons'); 
WRITELN ('Move the mouse around and click the left button'); 
WRITELN ('Click the right button for hardware mouse demo'); 


WRITELN; 

mTextCursor (software, $0000, $0718); { set s/w cursor 
mShow; { turn cursor on 
REPEAT 


mReleased (left, its); 

IF its.opCount > 0 THEN BEGIN 
mHide; { in case screen scrolls 
WRITELN ('Mouse is at column ', its.column, 

', row ', its.row); 


{ check left button 


mShow; 
END; 


{ cursor back on 
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mReleased (right, its); 
UNTIL its.opCount > 0; 


{ check right button } 
{ loop if not released } 


{ Now do the hardware mouse demo } 
CLRSCR; 
WRITELN ('Hardware cursor:'); 
WRITELN 
('Move the mouse, click left button’); 
WRITELN ('Type something and press Enter'); 
WRITELN ('Click right button to end demo'); 
mReset (theMouse); { clear old mouse status } 
mTextCursor (hardware, 2, 5); { set h/w cursor as small block } 
mShow; { and turn it on } 
REPEAT 
mReleased (left, its); 
IF its.opCount > 0 THEN BEGIN 
col := its.column DIV 8; 
row := its.row DIV 8; 
GOTOXY (col, row); 
WRITE ('?'); 
READLN (input); 


{ check left button } 
{ compute text position } 
{ move text pointer 


> 

{ prompt > 

{ get the input } 
> 


moveto (its.column, its.row); { restore position 
END; 
mReleased (right, its); { check right button 


UNTIL its.opCount > 0; { loop if not released 
{ Clean up afterwards } 
mTextCursor (hardware, 6, 7); € if graphics board, else 11,12 } 
mReset (theMouse); { reinitialize mouse } 
CLRSCR; 
END 
ELSE 
WRITELN (‘Mouse not present in system'); 
END. 


LISTING 5: MOUSEVNT.PAS 


PROGRAM mousevnt; { Illustrates mouse function 12 } 


USES dos, crt, mouse; 


TYPE mEvent = record { for recording mouse event } 
event, 

btnStatus, 

horiz, 

vert : WORD; 


END; 
mEvent; 
resetRec; 


{ 
PROCEDURE handler 
(Flags, CS, IP, AX, BX, CX, DX, SI, DI, 


{ Mouse event handler called by device driver } 
DS, ES, BP : WORD); 


INTERRUPT; 
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occurs at the BEGIN keyword). 
This code saves all the CPU 
registers and then sets DS to point 
to the data segment, enabling the 
routine to read or write any pro- 
gram global. The procedure also 
has direct access to registers, since 
they're named as parameters. Con- 
sequently, you can simply copy 
from registers into the fields of 
the record defined as the mEvent 
type (or into any other variable of 
type WORD). Afterward, control 
passes through the inline se- 
quence and returns to the device 
driver. 

In this way, the handler quickly 
saves a record of the event and 
returns. A more sophisticated pro- 
gram than the demo in Listing 5 
might instead stick the record into 
a linked list serving as a queue, so 
that several events can be stored 
up. 

In either case, the program 
must look periodically to see if a 
mouse event has occurred (by 
checking if the event field is non- 
zero or if the queue pointer is not 
nil). If a mouse event has oc- 
curred, the program must then 
take action. A necessary part of 
the action is resetting the indica- 
tor so that the same event isn’t 
processed more than once. The 
statement mous.event := 0; in the 
demo loop performs this step. 


DOING IT IN TURBO C 


The MOUSEVNT.C program (List- 
ing 6) is functionally similar to its 
Turbo Pascal counterpart, with 
one notable exception—the loca- 
tion of the buffer that saves the 
mouse event status. The Pascal 
version treats this buffer as a 
global, which is accessible from 
the interrupt-class handler. The 
same thing could be done in 
Turbo C by making the handler 
function an interrupt-class pro- 
cess. However, I treated it differ- 
ently due to a fundamental differ- 
ence between the Turbo Pascal 
and Turbo C compilers. 

Turbo Pascal makes it easy to 
insert the necessary inline code to 


continued on page 66 


Basically speaking, there's 
one choice... Turbo Basic! 


Compare the BASIC differences! 


Turbo Basic 1.1 


Compile & Link to 


stand-alone EXE 3 sec. 


28387 


Size of EXE 
Execution time a 
| w/80287 0.16 sec. 
| Execution time 
| w/o 80287 0.16 sec. 


QuickBASIC 4.0 QuickBASIC 4.0 
Compiler Interpreter 
7 sec. —— 
25980 -- 
16.5 sec. 21.5 sec. 
286.3 sec. 292.3 sec. 


The Elkins Optimization Benchmark program from March 1988 issue of Computer Language was used. 
The Program was run on an IBM PS/2 Model 60 with 80287 at 10 MHz. The benchmark tests compil- 
er’s ability to optimize loop-invariant code, unused code, expression and conditional evaluation. 


Turbo Basic® is the BASIC that 
lets even beginners write pol- 
ished, professional-looking pro- 
grams almost as easily as they 
can write their names. 

The others don’t. When you 
really examine them, you'll find 
that even though they may be 
““quick,’’ they make it hard to 
get where you're going. (Sort of 
like a car with an engine but no 
steering wheel.) 

Turbo Basic takes you farther 
faster—in the comfort of a sleek 
development environment that 
gives you full control. Naturally 
it has a slick, fast compiler, just 
like all Borland’s technically 
superior Turbo languages. It a/so 
has a full-screen windowed edi- 
tor, pull-down menus, and a 
trace debugging system. And 
innovative Borland features like 
binary disk files, true recursion, 


System Requirements: For the IBM PS/2™ and the IBM® family of personal 
computers and all 100% compatibles. Operating System: PC-DOS (MS-DOS) 
2.0 or later. Toolboxes require Turbo Basic 1.0. Memory: 384K RAM for 
compiler, 640K RAM to compile Toolboxes. 


“Customer satisfaction is our main concern; if within 60 days of purchase this 
product does not perform in accordance with our claims, call our customer 
service department, and we will arrange a refund. 

All Borland products are trademarks or registered trademarks of Borland International, Inc 


QuickBASIC is a registered trademark of Microsoft Corporation, Other brand and product names 
are rademarks of their respective holders. Copyright ©1988 Borland International, Inc. BI 1242 


and more control over your com- 
piling. Plus the ability to create 
programs as large as your sys- 
tem’s memory can hold—not 
just a cramped 64K. 

The critics agree. The choice 
is basic. Turbo Basic from 
Borland. 


Add another Basic advantage: 
The Turbo Basic Toolboxes 


¢ The Database Toolbox gives 
you code to incorporate into 
your own programs. You don’t 
have to reinvent the wheel 
every time you write new 
Turbo Basic database 
programs. 


The Editor Toolbox is all 
you need to build your own 
text editor or word processor, 
including source code for two 
sample editors. 


New! 


New! 


60-Day Money-back Guarantee * 


INTERNATIONAL 


6¢ With a total programming 
environment like Borland 
International’s Turbo Basic 

at the ready, even novice pro- 
grammers can soon write 
programs that look as if they’ve 
been polished by a professional 
... What really makes Turbo 
Basic special is its blinding 
speed, small size, and many 
added commands. Programs 
compiled with Turbo Basic are 
often much faster and smaller 
than those produced by other 
compilers. 


Ethan Winer, PC Magazine Best of 1987 


[Turbo Basic] is easy enough to 
use for the beginning program- 
mer and has enough power and 
sophistication for the profes- 
sional. It is an unbelievable 
achievement for the price. 


Giovanni Perrone, PC Week 


[Turbo Basic] simply blew away 
my optimization test ... these 
test results were truly wonderful 
surprises. 


T.A. Elkins, Computer Language 


Turbo Basic, simply put, is an 
incredibly good product. 
William Zachman, Computerworld 99 


oe 104 


For the dealer nearest you 
call (800) 543-7543 


BEGIN 
mous .event z= AX; 
mous.btnStatus := BX; 
mous ..horiz z= CX; 
mous. vert := DX; 
inline ¢ € Exi 
$8B/$E5/ { MOV 
$5D/ { POP 
$07/ { POP 
$1F/ { POP 
SSF/ { POP 
$5E/ { POP 
$5A/ { POP 
$59/ { POP 
$5B/ { POP 
$58/ { POP 
$CB ); { RETF 
END; 
Cosine Semaine = eee nce anim > 
BEGIN 
{ Set up screen } 
CLRSCR; 


GOTOXY (17, 25); 


> 
> 
? 
> 
> 
DX > 
> 
y 
> 
> 


WRITE ('Press left button for position, right to quit'); 


GOTOXY (27, 1); 


WRITELN ('MOUSE EVENT-HANDLING DEMO'); 


{ Set up mouse } 
mReset (m); 
IF m.exists THEN BEGIN 


mInstTask ($14, seg (handler), ofs (handler)); 


mous .event 
mShow; 


:= 0; 


{ Loop to perform demo } 
REPEAT 
IF mous.event = 
mHide; 
WRITELN ('X = 
mShow; 
mous.event := 0; 
END; 
UNTIL mous.event = $10; 


{ Clean up and quit } 
mHide; 
mReset 

END; 
CLRSCR; 
END. 


(m); 


LISTING 6: MOUSEVNT.C 


4 THEN BEGIN 


', mous.horiz : 


5, 8, ¥ = Uy mous; vert: 2 15) 


/* MOUSEVNT.C: Illustration of mouse function 12 */ 


/* INCLUDES */ 
#include <stdio.h> 
#include <dos.h> 
#include <mouse. i> 


/* DEFINES */ 
#def ine ROMBIOS 


/* TYPE DEFINITION */ 
typedef struct { 
unsigned event, 
btnStatus, 
horiz, vert; 
} mEvent; 


int86 (0x10, &inreg, &outreg) 


/* structure for recording mouse event 


/* event that occurred 
/* current button status 
/* position where event occurred 


t processing for far return to device driver } 
SP, BP } 


lf 
dd 
fl | 
sf 
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exit properly from the handler. 
Turbo C also supports inline code, 
but you need to also have an 
assembler that the compiler can 
run as a child process in order to 
translate the inline assembly lan- 
guage. If you don’t have an assem- 
bler, you can’t use inline code. 
Thus, I chose a different way to 
store the mouse event status. 

When DOS starts a program, it 
attaches a prefix structure called 
the Program Segment Prefix (PSP) 
to the memory image. The lower 
half of this 256-byte structure is 
rigidly formatted and should 
never be modified by the pro- 
gram. The upper 128 bytes, how- 
ever, are available for the pro- 
gram to use. Turbo C programs 
don’t ordinarily use this space, so 
we can safely grab some of it. 

You can get the segment 
address of the PSP in a couple of 
ways. The simplest way is to read 
the system global _psp, which is 
furnished by DOS.H and is auto- 
matically initialized when the pro- 
gram begins execution. The _psp 
global contains the PSP segment. 
Note that the mouse setup in 
MOUSEVNT.C uses _psp to initial- 
ize the pointer to the event buffer. 

Because it’s called by the mouse 
device driver (and therefore 
inherits the device driver’s data 
segment), the handler routine 
has no access to globals within 
MOUSEVNTC (physically, 
the handler is a part of 
MOUSEVNT.C; functionally, it’s a 
subroutine of the device driver). 
For that reason, we have to use 
another way to calculate the PSP 
segment. The PSP has a value 10H 
less than the code segment in the 
Turbo C near memory models 
(Tiny, Small, and Compact). Thus, 
we can easily find the PSP seg- 
ment by subtracting 10H from the 
CS register (see the second state- 
ment in the handler function). 

While MOUSEVNT.C is a sim- 
ple demonstration of mouse event 
handling, it contains all of the ele- 
ments necessary for more com- 
plex applications. The main part 
of the program constantly loops. 
With each loop, the program 
checks the event field to see if an 
event has occurred; if one has 
occurred, the program takes 


action. The left button 
mous->event = = 4 

produces a position report on the 
screen. The right button 


mous->event = = 0x10 


terminates the loop, ending the 

program. 

Function 13 and 14: Light Pen 

Emulation (mLpenOn/ Off). The 

reset function sets light pen emu- 

lation ON by default. Software 
that expects light pen input then 
interprets the mouse cursor as the 
light pen’s position. 

Not much software uses a light 
pen, so it’s seldom necessary to 
call these functions. You may need 
them when you’re writing an 
application that uses a light pen 
that’s independent of the mouse. 
In this case, you should turn emu- 
lation OFF immediately after 
reset, so that your program isn’t 
confused by dual signals. 

By now, you're probably eager 
to start creating your own spectac- 
ular user interface around a 
mouse. You should have enough 
information and the right tools to 
begin. I leave you with three 
pieces of advice about mouse 
programming: 

1. Use a handler installed via 
function 12 as much as pos- 
sible, rather than other status- 
checking calls. 


2. Check the mouse event status 
often, preferably in a loop. 
Check elsewhere as well if you 
leave the loop for lengthy 
periods. 


3. When you don’t want the 
mouse to be available to the 
user, save the cursor position 
and hide it. Later, when re- 
opening the mouse for busi- 
ness, reset the cursor position 
and restore the cursor to its 
former position. 


See you in Part 2, where we'll 
hunt down the mouse in graphics 
territory. Ml 


Kent Porter is the author of Stretch- 
ing Turbo Pascal and numerous 
other programming books. He is a fre- 
quent contributor to TURBO 
TECHNIX. 


Listings may be downloaded from 
CompuServe as CMOUSE.ARC. 


/* LOCAL PROTOTYPES */ 
void clrScr (void); 
void gotoxy (int, int); 
/* sh Onecare a pw Be ee, wen Sn ws St | ee ee we to 0 om ee in we eaten aw es Sie aw 0 
void far handler (void) /* event handler called by device driver 
{ 

mEvent far *save; 
unsigned a, b, c, d; 


/* pointer to save area in diff segment 
/* temp storage of registers 


a= JAX, b = _BX, c= _CX, d = _DX; 
save = MK_FP (_CS - 0x10, 0x00CO); 
save->event = a; 

save->btnStatus = b; 

save->horiz = c; 

save->vert = d; 


/* save registers 
/* point to PSP user area 
/* stuff registers into it 


Ne IR SOO II TONES EI */ 
main () 

{ 

mEvent far *mous; 

resetRec *m; 


/* Set up screen */ 
clrScr (); 
gotoxy (17, 24); 
printf ("Press left button for position, right to quit"); 
gotoxy (27, 0); 
puts ("MOUSE EVENT-HANDLING DEMO"); 


/* clear screen 


/* Set up mouse */ 
m = mReset (); /* initialize mouse 
if (m->exists) { /* if mouse exists... 
miInstTask (0x14, FP_SEG (handler), FP_OFF (handler)); 
mous = MK_FP (_psp, Ox00CO); /* point to event buffer 
mous->event = 0; /* reset event signal 


mShow (); /* show cursor 
/* Loop to perform demo */ 
do { 
if (mous->event == 4) ¢ /* if left button operated... 
mHide (); /* hide cursor in case of scroll 


printf ("\nX = 43d, Y = %3d", mous->horiz, mous->vert); 
mShow (); /* show cursor again 
mous->event = 0; /* reset event signal 
> 
} while (mous->event != 0x10); /* loop til right button 


/* Clean up and quit */ 


mHide (); /* cursor off 
mReset (); /* reinitialize mouse 
> 
elrSer t= /* clear screen 
BP PO SSSI REO sa */ 
void clrScr (void) /* clear screen 
{ /* Uses ROM BIOS int 10h to reset video mode to itself 
struct REGS inreg, outreg; 
inreg.h.ah = OxOF; /* get current mode 
ROMBIOS; 
inreg.h.al = outreg.h.al; /* copy mode 
inreg.h.ah = 0; /* reset to same mode 
ROMBIOS; 
Bal fel TOs =) 


void gotoxy (int col, int row) /* position text cursor 
/* uses ROM BIOS int 10h 


struct REGS inreg, outreg; 


inreg.h.ah = 2; /* fcn 2 sets cursor position 
inreg.h.bh = 0; /* video page 0 is active 
inreg.h.dh = row; 
inreg.h.dl = col; 
ROMBIOS; 
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TURBO C 


++,-- 


There’s more to adding or subtracting by one 


than meets the eye. 


Bruce F. Webster 


Part of the strength and power of Turbo C 
comes from your freedom to build tight, 
precise expressions that do exactly what 
you want without taking up a lot of source 
code. Much of this freedom comes from 
C’s large list of operators and the flexibil- 
ity you have in using them. 

New users of C sometimes have problems with 
four of C’s operators: preincrement, predecrement, 
postincrement, and postdecrement. The names seem 
formidable, but you can easily break them down: 
“pre” means “before,” “post” means “after,” “incre- 
ment” means “add 1,” and “decrement” means “sub- 
tract 1.” So, assuming that x is a variable in some 
expression, Table 1 shows you how the operators 
look and what they do. 


SQUARE ONE 


OPERATOR NAME EXAMPLE MEANING 

Preincrement hx add | to x before evaluat- 
ing the expression 

Predecrement --x subtract | from x before 
evaluating the expression 

Postincrement xt++ add | to x after evaluating 
the expression 

Postdecrement x-- subtract | from x after 


evaluating the expression 
Table 1. Turbo C’s increment and decrement operators. 


Consider the postincrement operator. The Turbo 
C statement 


x++; 


is roughly equivalent to the Turbo Pascal statement: 
ee Gas Kd 
I say “roughly” because you can put x++ into 
expressions, something the Pascal language won’t let 
you do withx:=x+1. 

For example, the following statement means 
“assign the value of x to y, then add | to x”: 


y= X++) 
If x had a value of 42 prior to executing that state- 


ment, then x would have a value of 43 and y would 
have a value of 42 after the statement executed. 


Notice that the statement below has a completely 
different result: 
y = ++x; 
This statement adds | to x before assigning x to y, so 
that if x starts out with a value of 42, both x and y 
end up with a value of 43 after the statement executes. 
Perhaps the most common use of these operators 
is within loops, especially for loops. The typical for- 
mat is: 
for (i= start; i <= finish; i++) € 
<statements>; 
) 
This for loop executes <statements> with the vari- 
able i going from start to finish, being incremented 
by 1 each time. You can build the same structure with 
a while loop: 
i = start; 
while (i <= finish) € 

<statements>; 

i++; 
3 

These examples show how the increment and 
decrement operators work, but they don’t really dem- 
onstrate these operators’ usefulness. Consider the 
short program in Figure 1. 

The third executable statement—the while loop— 
does all the work of counting how many characters 
are in the string variable line. Note that the while 
structure itself doesn’t have any statements to exe- 
cute; the counting work is done within the expres- 
sion line[count ++] inside the parentheses. 

How does this work? First, remember that the 
while loop will repeat its evaluation of the expression 
within the parentheses until the expression takes on 
a value of 0 (or FALSE). Strings in C (such as line) 
are terminated with a NUL (ASCII 0) character. So, 
this loop will sit there, with count incrementing itself, 
until a NUL character is encountered at line[count]. 

The variable count starts off at 0, so the while loop 
tests line[0], then increments count. The loop con- 
tinues this process, incrementing count by 1 each 
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UNLEASH YOUR 80386! 


Your 80386-based PC should run twoto 
three times as fast as your old AT. This 
speed-up is primarily due to the doubl- 
ing of the clock speed from 8 to 16 MHz. 
The new MicroWay products discussed 
below take advantage of the real power 
of your 80386, which is actually 4 to 16 
times that of the old AT! These new pro- 
ducts take advantage of the 32 bit regis- 
ters and data bus of the 80386 and the 
Weitek 1167 numeric coprocessor chip 
set. They include a family of MicroWay 


80386 compilers that run in protected 
mode and numeric coprocessor cards 
that utilize the Weitek technology. 

The benefits of our new technol- 
ogies include: 
e An increase in addressable memory 
from 640K to 4 gigabytes using MS- 
DOS or Unix. 
eA 12 foldincrease in the speed of 32 bit 
integer arithmetic. 
¢ A 4 to 16 fold increase in floating point 


t 88888000,» 


mW1167 Numeric 
Coprocessor Board 


MicroWay 80386 Compilers 


NDP Fortran-386 and NDP C-386 are globally 
optimizing 80386 native code compilers that 
support a number of Numeric Data Processors, 
including the 80287, 80387 and mW1 167. They 
generate mainframe quality optimized code and 
are syntactically and operationally compatible to 
the Berkeley 4.2 Unix £77 and PCC compilers. 
MS-DOS specific extensions have been added 
where necessary to make it easy to port pro- 
grams written with Microsoft C or Fortran and 
R/M Fortran. 

The compilers are presently available in two 
formats: Microport Unix 5.3 or MS-DOS as ex- 
tended by the Phar Lap Tools. MicroWay will port 
them to other 80386 operating systems such as 
OS/2 as the need arises and as 80386 versions 
become available. 

The key to addressing more than 640 kbytes 
is the use of 32-bit integers to address arrays. 
NDP Fortran-386 generates 32-bit code which 
executes 3 to 8 times faster than the current 
generation of 16-bit compilers. There are three 
elements each of which contributes a factor of 2 
to this speed increase: very efficient use of 
80386 registers to store 32-bit entities, the use of 
inline 32-bit arithmetic instead of library calls, 
and a doubling in the effective utilization of the 
system data bus. 

An example of the benefit of excellent code isa 
32-bit matrix multiply. In this benchmark an NDP 
Fortran-386 program is run against the same 
program compiled with a 16-bit Fortran. Both 
programs were run on the same 80386 system. 
However, the 32-bit code ran 7.5 times faster 
than the 16-bit code, and 58.5 times faster than 
the 16-bit code executing on an IBM PC. 

NDP FORTRAN-386™ 
NDP C-386™ 


MicroWay Numerics 


The mW1167™ is a MicroWay designed high 
speed numeric coprocessor that works with the 
80386. It plugs into a 121 pin “Weitek” socket 
that is actually a super set of the 80387. This soc- 
ket is available on a number of motherboards 
and accelerators including the AT&T 6386, 
Tandy 4000, Compaq 386/20, Hewlett Packard 
RS/20 and MicroWay Number Smasher 386. It 
combines the 64-bit Weitek 1163/64 floating 
point multiplier/adder with a Weitek/Intel de- 
signed “glue chip”. The mW1167™ runs at 3.6 
MegaWhetstones (compiled with NDP Fortran- 
386) which is a factor of 16 faster than an AT and 
2 to 4 times faster than an 80387. 

mW1167 16 MHz 

mW1167 20 MHz 


Monoputer™ - The INMOS T800-20 Trans- 
puter is a 32-bit computer on a chip that features 
a built-in floating point coprocessor. The T800 
can be used to build arbitrarily large parallel pro- 
cessing machines. The Monoputer comes with 
either the 20 MHz T800 or the T414 (a T800 
without the NDP) and includes 2 megabytes of 
processor memory. Transputer language sup- 
port from MicroWay includes Occam, C, Fortran, 
Pascal and Prolog. 

Monoputer T414-20 with 2 meg’ ...$1495 
Monoputer T800-20 with 2 meg’ ...$1995 


Quadputer™ can be purchased with 2, 3 or 4 
transputers each of which has 1 or 4 megabytes 
of memory. Quadputers can be cabled together 
to build arbitrarily fast parallel processing 
systems that are as fast or faster than today’s 
mainframes. A single T800 is as fast as an 
80386/mW1167 combination! 

Biputer™ T800/T414 with 2meg' ... .$3495 
Quadputer 4 T414-20 with 4 meg’ ...$6000 
‘Includes Occam 


speed over the 80387/80287 numeric 
coprocessors. 

Equally important, whichever Micro- 
Way product you choose, you can be 
assured of the same excellent pre- and 
post-sales support that has made Micro- 
Way the world leader in PC numerics 
and high performance PC upgrades. 
For more information, please call the 
Technical Support Department at 

617-746-7341 
After July 1988 call 508-746-7341 


MicroWay* 
80386 Support 


80386 Multi-User Solutions 


AT8™ - This intelligent serial controller series is 
designed to handle 4 to 16 users in a Xenix or 
Unix environment with as little as 3% degrada- 
tion in speed. It has been tested and approved by 
Compag, Intel, NCR, Zenith, and the Department 
of Defense for use in high performance 80286 
and 80386 Xenix or Unix based multi-user 


Phar Lap™ created the first tools that make it 
possible to develop 80386 applications which 
run under MS-DOS yet take advantage of the full 
power of the 80386. These include an 80386 
monitor/loader that runs the 80386 in protected 
linear address mode, an assembler, linker and 
debugger. These tools are required for the MS- 
DOS version of the MicroWay NDP Compilers. 
Phar Lap Tools 


PC/AT ACCELERATORS 
287Turbo-10 10 MHz 


MATH COPROCESSORS 
80387-20 20 MHz 

80387-16 16 MHz 

80287-10 10 MHz 

80287-8 8 MHz 


The World Leader in PC Numerics 

P.O. Box 79, Kingston, Mass. 02364 USA (617) 746-7341 
32 High St, Kingston-Upon-Thames, U.K., 01-541-5466 
St. Leonards, NSW, Australia 02-439-8400 


main() 
{ 
char _lLine(128]; 
int count; 


count = 0; 
scanf("%s", Line); 
while (line[count++] ); 


/* initialize the counter to 0 */ 
/* get a string from the user */ 
/* count chars in the string */ 


printf("There are %d characters in the line\n",--count); 


Figure 1. Doing real work with an empty while statement. 


{ 
float *myptr,mylist [20]; 


myptr = &mylist(0]; /* point myptr at start of mylist */ 


while (myptr < &mylist[20]) { 
*myptr = 1.0; 
myptr++; 

> 


Figure 2. Incrementing printer referents. 


++, -- 


continued from page 68 


time, until line[count] is NUL, and 
the loop ends. Note, however, that 
count will be incremented one last 
time after the NUL is detected, and 
so count will be too large by 1. 
That’s why we put --count in the 
printf() call: we first decrement 
count by 1, then print out its value. 


POINTERS 


When a pointer-type variable is 
being incremented or decre- 
mented, the ++ and -- operators 
work a little differently. They still 
add or subtract a fixed value from 
their operands, but that value now 
depends upon the pointer type— 
you can no longer assume the 
value to be 1. 

Suppose you have some data 
type called mytype, and that myptr 
is declared to be a pointer to 
mytype as shown below: 
mytype _*myptr; 

Given the above declaration, the 
expression 

myptr++; 

no longer means “add 1 to 
myptr.” Instead, it means “add 
sizeof(mytype) to myptr.” In other 
words, the address stored in myptr 
is incremented by the number of 
bytes that a variable of type 
mytype uses. 

How would this be helpful? 
Consider the code in Figure 2. 
Here, mylist is a list of 20 ele- 
ments of type float, and myptr is a 
pointer to type float. The while 
loop starts with myptr pointing to 
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the first element in mylist. Each 
pass through the loop points 
myptr to the next element in the 
list. The expression myptr ++, 
adds the size (in bytes) of type 
float to myptr, “bumping” myptr 
to the next element in mylist. 

If the size of the float type is 
not taken into account, increment- 
ing myptr only points myptr to 
the second byte in the same float- 
ing point number that myptr 
pointed to originally—perhaps a 
useful thing to do from time to 
time, but not what we want to do 
here. 

Pointers, then, are a special 
case for incrementing and decre- 
menting. The assumption in 
incrementing or decrementing a 
pointer is that the pointer is point- 
ing to a list of items that have the 
same data type. The idea is to 
point to the next (or previous) 
item in the list, not simply to add 
or subtract one byte to or from the 
address of the pointer’s referent. 


PITFALLS 


You need to be aware of potential 
problems using these operators. 
For example, consider the follow- 
ing statements: 

x = 10; 

Yes > 2 Xtt ot 5% = =xe 

After these statements execute, 
what values do x and y have? The 
answers are 10 and 72, respec- 
tively. Why? Because the --x takes 
place before the expression is 
evaluated at all, reducing x to 9. 
3*9+ 5 * 9 is 72. x is then incre- 
mented back up to 10 with x++. 


A second problem, alluded to 
above, deals with pointers. In the 
test() function in the following 
program, note that we’re passing a 
pointer to a long variable, so that 
we can change it within test() and 
have that change reflected 
elsewhere: 
void test(val) 
long *val; 
€ 

*val++; 
> 
main() 
{ 

long iN 

i = 0; 

test(&i); 

printf("i = %d \n",i); 
> 
However, when the program runs, 
you'll find that i is not (necessar- 
ily) 1. That’s because the expres- 
sion *val ++ within Test() does a 
postincrement on the address in 
val rather than on the long value 
pointed to by *val. To increment 
the value, you need to write 
(*val) ++ instead. This forces the 
++ operator to act upon *val 
rather than just val. 


CONTROL, CONTROL 

The increment and decrement 
operators in C are popular be- 
cause they’re concise, useful, and 
allow tremendous control over 
values in iterative operations. Two 
cautions when you use them: 


® Comment heavily; the terse- 
ness of C in general, and the 
terseness of these operators in 
particular, makes extra com- 
menting necessary. 

© Be sure that in any given ex- 
pression, increment and decre- 
ment do what you want them to 
do. Look carefully at which 
side of the operand the opera- 
tor is placed, and make sure 
you understand the difference 
between incrementing or 
decrementing a pointer and 
incrementing or decrementing 
the pointer’s referent. 


Look before you code. That’s 
one of several important axioms 
in working with C, and never 
more necessary than when work- 
ing with ++ and --. @ 


Bruce Webster is a computer merce- 
nary living in the Santa Cruz moun- 
tains. He can be reached via MCI 
MAIL (as Bruce Webster) or on BIX 
(as bwebster). 


A QUATTRO SAVE 


TRANSLATOR 


Quattro’s open architecture lets you create 
your own translators for writing spreadsheets to disk 


in any format you choose. 


Bruce F. Webster 


With release of the Quattro Developer’s 
Toolkit, you can join the Quattro add-in 
development team and begin writing 
your own extensions and additions to 
Borland’s Professional Spreadsheet. Start- 
ing in this issue, TURBO TECHNIX will 
present a series of articles on creating custom 
Quattro add-in programs with Turbo C and Turbo 
Pascal. Because special libraries and start-up code 
are needed to create Quattro add-ins, these pro- 
grams assume that you have the Quattro Developer’s 
Toolkit. 

In this issue, we'll look at file translator drivers, or 
“translators.” A translator performs one of two tasks, 
depending upon whether information is moving into 
or out of Quattro. A retrieve translator converts a file 
into a series of records that Quattro understands. A 
save translator saves a Quattro spreadsheet as a disk 
file using a defined format. 

As a simple example, consider a translator that 
saves a spreadsheet to disk. Specifically, the transla- 
tor saves the current Quattro spreadsheet as a plain 
ASCII text file, with each row of cells taking up one 
line and all cells within a row separated by commas. 
Cells that contain text (such as label cells) are saved as 
text surrounded by quotation marks; thus, any com- 
mas embedded in the text won’t be confused with 
commas that separate two adjacent cells. Empty rows 
are inserted as blank lines; empty cells in a non- 
empty row are inserted as a pair of double quotes 


*. 


HOW A SAVE TRANSLATOR WORKS 


When Quattro saves a file to disk, it checks the 
extension of the output filename provided by the 
user, then loads the corresponding file translator. 
Quattro looks in its current directory for a translator 
file named FSxxx.TRN, where xxx is the output file 
extension. For example, if Quattro is told to save the 
current spreadsheet to BUDGET.ASC, it looks for a 
file named FSASC.TRN, loads that file, and then uses 
it to save the spreadsheet. 


PROGRAMMER 


Quattro opens the output file itself and starts pass- 
ing spreadsheet records to the save translator. Quattro 
contains two types of spreadsheet records: cell and 
noncell. A cell record holds the contents of a given 
cell (i.e., the spreadsheet’s data), and can be one of 
several types (most notably, INTEGER, NUMERIC, 
LABEL, and FORMULA). Noncell records hold 
spreadsheet settings and other descriptive 
information. 

Quattro passes these spreadsheet records one at 
a time to the save translator. The translator then 
decides what to do with each record. Typically, the 
translator converts each record to a format appro- 
priate to the type of file it’s creating. Next, the trans- 
lator writes the translated record to that new file. 
While the translator can ignore or combine records, 
it always receives each record one at a time, in this 
order: 


® WKQBOF (WKQ Beginning-Of-File) record 
@ all noncell records 
® all cell records 
© WKQEOF (WKQ End-Of-File) record 
The translator can request that Quattro skip all 
the noncell records; likewise, after receiving all the 


noncell records, the translator can request that 
Quattro skip all the cell records. 


STRUCTURE OF A TRANSLATOR 


A save translator must contain at least these four 
functions: init_save(), cvt_rec(), end_nonc(), and 
end_save(). 


init_save(). This function handles initialization of 
the save translator. (init_save() does not open the 
output file—that step is performed by Quattro.) 
init_save() takes the following form: 
int init_save(unsigned h, 

char *filename, 

unsigned password); 


continued on page 74 
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TURBO C 


Borland’s New Professional Spreadsheet 


Quattro: Twice the speed. 
Twice the power. Half the price. 


uattro”, our new professional 

spreadsheet, proves there 

are better and faster ways to 
do everything. To do graphics. To 
recalculate. To do macros. To save 
and retrieve. To search, sort, load. 
To do anything and everything that 
state-of-the-art spreadsheets 
should do. 


Quattro gives you 
presentation-quality 
graphics 

Quattro brings new highs in 
quality graphics to your spread- 
sheet. It also brings Postscript™ 
support and new variety and 
diversity to the kinds of graphs 
and graphics you can produce 
from your spreadsheet, and you 
can produce hard copy of your 
graphics—with either printer 
or plotter—without leaving the 
spreadsheet. All you do is hit 
“Print.” Quattro makes it easy 
to get hard copy—and you don’t 
have to buy a separate graphics 
program. 


“Customer satisfaction is our main concern, within 60 days of purchase thes product does not perform in 
accordance with our claims, call our customer service department, and we wil arrange a velund 
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Quattro recalculates much 
faster than you-know-who 

The smartest and fastest way 
to recalculate a spreadsheet is to 
do what Quattro does, something 
called “intelligent recalc,” which 
in English means you only re-count 
the numbers that count. 

In a spreadsheet, not all numbers 
are born equal and changing one 
number doesn’t always change 
everything, so Quattro recalculates 
just the formulas that matter, not 
all the formulas it knows. (You 
wouldn’t reshoot a whole movie 
just because you changed one 
scene, but unfortunately, that’s the 
way 1-2-3 does it—and that’s why 
it takes so long.) 


Quattro demystifies 
Macros and makes 
your work go faster 

Using macros—electronic short- 
cuts—is easy with Quattro. Quattro 
offers a complete macro debugging 
environment as you “single-step” 
through your macros and record 
them as you work. 


All Borland products are trademarks or regstered trademarks of Borland international, inc 1-2-3 1s 2 
registered trademark of Lotus Development Corp. S07! \s a registered trademark of Symantec Corp /Turer 


Hall Publishing Division Other brand and product names are trademarks or registered Irademarks of their 
respective Nolders Copyright ©1988 Borland International BI 12064 


Expenses 


If you know how to use 
1-2-3, you know how 
to use Quattro 


You don’t have to learn a whole 
new program. Quattro works 
directly with all 1-2-3 file formats. 
No importing/exporting or macro 
translation is required. Quattro can 
also load and save ASCII, Paradox®, 
and dBASE? files. 

Compatible with 1-2-3? Yes. 
Faster than 1-2-3? Yes. 
Technically superior to 1-2-3? Yes. 
Half the price of 1-2-3? Yes! 


44 ...\t's a perfect choice 
for either the novice spreadsheet 
user or for someone who has 
mastered every arcane twist 
of 1-2-3. 


Quattro includes SQZ!*° Plus 
data compression 

A special implementation of SQZ! 
Plus, the spreadsheet file compres- 
sion utility, is built into Quattro 
and comes to you absolutely free! 
SQZ! Plus for Quattro automatically 
compacts and expands Quattro 
spreadsheets by up to 95% during 
file saving and retrieving. 


Inventory Levels 


| Quattro: Natural 
| Evolution 


1970 1979 1982 1987 
HAND-HELD CALCULATOR VISICALC” LOTUS 1-2-3° QUATTRO™ 


Quattro: The Professional Spreadsheet 


FEATURE QuaTTRO tous 
ReCalc Cash Flow Model (5K cells) 27 sec. 2.90 see. 
3 | Delete Row 15K cells (Recalc Time) .76 sec. 2.38 sec. i 
& | Load File (15K cells) 15.9 sec. 19.8 sec. 
ity Page Down (A1 to A1000) 12.2 sec. 17.4 sec. 
Presentation-quality Graphics | YES NO 
|_| Graph Type 6 
2 | raph Types 10 | 
| | Integrated Graph Printing YES | NO 
iC 
iss! Full Graph Customization YES NO 
Ss 
| | On-Screen Font Styles 11 1 
| PostScript Support | YES NO 
_User-modifable Menus YES NO 
E Menu Shortcuts YES NO 
= ‘ 
bs Pull-down menus YES NO 
Fe Point and Press Editing YES NO 
|_| Automatic Installation YES | NO 
| ™ | Macro Learn Mode YES NO 
= Maximum Number of Macros Unlimited 27 
i> | Single Step Macro Debugging Environment YES NO 
} -+ - a - —— - 
| Price $247.50 $495 
60-Day Money-Back Guarantee* Benchmark details available upon request. 
Get Quattro the For the dealer nearest you 
,’ 


professional spreadsheet phy 1 (800 543-7543 
for only $247.50 Call (800) 943- 

Quattro is so advanced it’s easy 
to use and it’s half the price of 
1-2-3. It’s fully compatible with all 
your existing 1-2-3 files and 


macros—but it makes everything in 
them look better, print better and 


makes your work go faster. BORLAND 


UCN TERNATIOON At 


For the IBM PS/2 and the IBM family of personal 
computers and all 100% compatibles. 


typedef struct { 
unsigned rectype; /* record type */ 
unsigned reclen; /* record body length */ 
char recbody; /* start of record body */ 


} REC_HDR; 
typedef struct { 
int doserr; /* error code (0 if none) */ 
unsigned int rectype; /* record type */ 
int reclen; /* record length */ 
char *recdata; /* pointer to record body */ 


} RECDESC; 


Figure 1. The REC_LHDR and RECDESC types used by a Quattro save 


translator. 


| 86/21/87 Sey 
06/22/87 SAN DIEGO 
86/23/87 SAN 
86/24/87 SAN | 
86/25/87 

86/26/87 SAN 
86/27/87 


B?: (D4) 31949 
16-Mar-88 11:25 AM 


Figure 2. The spreadsheet SAMPLE.WKQ on the Quattro screen. 


“wu "EXPENSE REPORT FOR ALLISON SPRINGS" 
"iu "WEEK ENDING JUNE 27, 1987" 


THE SAVE TRANSLATOR 
continued from page 71 


h is the DOS file handle for the 
file that Quattro has opened. 
filename is the complete DOS 
pathname, and password is a flag 
that indicates if the user has 
entered a password. 

init_save() returns one of two 
values: 0 or SKIP_NON_CELLS. 
If init_save() returns 0, then 
Quattro passes the noncell 
records, starting with BOF; if 
init_save() returns 
SKIP_NON_CELLS, Quattro 
passes only the cell records. 


evt_rec(). This function retrieves 
the Quattro spreadsheet records 
one at a time. It converts each 
record to the required output for- 
mat, and writes that converted 
record to the output file. cvt_rec() 
typically appears as shown below: 


RECDESC *cvt_rec(REC_HDR r); 


Figure 1 shows the types 
REC_HDR and RECDESC, which 
are defined in the header files 
included with the Quattro Devel- 
oper’s Toolkit. The record type 
and length fields together are 
called a record header. The field 
recbody is the beginning (the first 
byte) of the record body. 

The basic structure of cvt_rec() 
is usually a switch statement, 


"DAY OF WEEK", "DATE", "LOCATION", "TRANS.", "HOTEL", "ENTERTAIN", "MEALS", "TOTAL","", "DAY OF WEEK","DATE", "MEALS" 


"SUNDAY", 31949, "SAN DIEGO", 89,0, 10, 36.95, 135.95, "", "TUESDAY", 31951, 35 
"MONDAY", 31950, "SAN DIEGO", 9,67,32.5, 19.56, 128.06, "", "SUNDAY", 31949, 36.95 


"TUESDAY", 31951,"SAN DIEGO", 27.55,67,0,35,129.55,"", "WEDNESDAY", 31952,45.15 


WEDNESDAY", 31952, "SAN DIEGO", 12.5,67,98.1,45.15,222.75 
"THURSDAY", 31953, "SAN DIEGO", 0,67,0,24.25,91.25 
MFRIDAY",31954,"SAN DIEGO",0,67,0,28.55,95.55 
"SATURDAY", 31955, "SAN JOSE", 133,67,0,0,200 


NTOTAL", "1, "274 .05.402,140.6, 189.46, 1003.11 


Figure 3. The spreadsheet SAMPLE. WKQ , translated to comma-delimited ASCII format. 


based on r.rectype, which handles 
each record according to its type. 

cvt_rec() is expected to return a 
pointer to a RECDESC structure. 
This structure must be declared as 
static so that it continues to exist 
between calls to cvt_rec(). The 
entire RECDESC structure should 
be initialized to zero. However, 
the doserr field can be used to 
prematurely abort the entire save 
process, in case of file corruption 
or other errors. To abort, set 
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doserr to one of the following 
values, which are predefined in 
the header files: 


DE_CORRUPT~— Save the file to 
disk with this record as the last 
record. 


DE_ABORT—Don’t save the file; 
delete the specified file from disk. 


end_nonc(). Quattro calls 
end_nonc() to signal that all of the 
noncell (spreadsheet information) 
records have been passed to the 
translator. end_nonc() is shown 
below: 


int end_nonc(void); 


All records passed by Quattro 
after it calls end_nonc() are cell 
records. At this point, you can tell 
Quattro to skip all the cell records, 
according to which of the follow- 
ing two values are returned by 
end_nonc() to Quattro: 


0—Pass all cell records. 


SKIP_CELLS—Skip all cell 
records. 


If end_nonc() returns 
SKIP_CELLS, then Quattro 
completes the save process 
without passing any additional 
spreadsheet records. 


end _save(). end_save() is pro- 
vided for the convenience of the 
translator, and typically is used to 
release memory heaps or to close 
any auxiliary files opened by the 
translator. (Quattro opens and 
closes the data file selected by 
the user.) A return value is not 
required. end_save() is shown 
below: 


void end_save(void); 


More about translator functions. 
You can, of course, have many 
more functions within your save 
translator. However, you must 
include the four functions discuss- 
ed above, and they must contain 
the declarations shown above; 
otherwise, you won't be able to 
link those functions with the 
necessary routines to produce an 
executable file translator. Also, 
you cannot put a main() function 
into your translator! 


A SIMPLE TRANSLATOR 


FSASC.C in Listing | is a simple 
save translator that writes a 
Quattro spreadsheet as an ASCII 
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LISTING 1: FSASC.C 


/* FSASC.C -- Comma-delimited save driver 


author: David Golden (minor changes by Bruce F. Webster) 
last update: 08 March 1988 
compiler: Turbo C 1.5 


link files: COSAVEC.OBJ, QC.LIB, CC.LIB 


This example uses 'cvt_rec' to convert records. Formula records 
are converted to either a NUMBER or LABEL record. 
*/ 


#include <quattro.h> /* general Quattro Toolbox header file */ 
#include <qdriver.h> /* additional header file for translators */ 


char out [300]; /* output buffer must be external to any 
procedure to ensure it stays in existence 
upon return to Quattro */ 


unsigned handle; /* file handle stored here */ 


/* * * Procedure specific to saving comma-delimited * * */ 


/* 
Procedure 'fillin' that 'fills in' by generating: 
1) 'null' fields that serve as placeholders for blank cells ¢ "" ) 
2) 'null' lines that serve as placeholders for blank rows 
( just CR/LF ) 


Receives: pointer to cell record that contains header information 
needed (the cell col and row) 


Returns: 
=f 


nothing 


int lastcol=0; 
int lastrow=0; 


/* column for last cell written */ 

/* row for last cell written */ 

int foundinrow=0; /* 'true' if cell already written out 
for this row */ 


/* all record types have header info in common */ 
void fill in(NUMBER_REC *r) 
{ 


int i,num_lines,num_flds,str_len; 
int col = r->col; 
int row = r->row; 


if(row > lastrow) 
{ /* generate end of line sequence followed by as many blank lines 
as needed */ 
out [0] = 0x00; /* ensure we concatenate at start of buffer */ 
for( num_lines = row-lastrow, i=0 ; i < mum_lines ; i++ ) € 
strcat(out,"\r\n"); 
/* output the buffer every 125 iterations to guarantee we 
don't overflow: 125*2=250 ( <300 ) */ 
if(€ €1%125)==124 ) € 
_write(handle, out, strlen(out) ); 
out [0] = 0x00; 
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By 

> 

if( strlen(out)>0 ) /* flush buffer */ 
_write(handle, out, strlen(out) ); 


lastrow=row; 

lastcol=0; 

foundinrow=0; 
> 


/* generate field separators to go between this field 
and previous one, and if necessary create null fields 
for the empty cells */ 

out [0] = 0x00; 

if (foundinrow) 
strcat(out,","); 


/* generate null fields (including preceding comma) if an empty 
cell preceded this one (in the same row) */ 


/* see if we need to create any null fields to precede this one */ 


if(! foundinrow) 
num_flds=col; 

else 
num_flds=col-lastcol-1; 


/* row starts with empty cells */ 


for( i=0 ; i<num_flds ; i++ ) € 
streat(out, "\"\","); 
if( (i%90) == 89 ) € 
_write(handle, out, strlen(out) ); 
out [0] = 0x00; 
> 
> 
if( (str_len=strlen(out)) > 0 ) /* flush buffer */ 
_write(handle, out, str_len ); 


lastcol = col 
foundinrow = 
return; 


1; 


init_save() function 


Initialize save driver. This is the first procedure called. 
Should save as an extern the file handle passed to it since 
it is not passed on subsequent calls. Quattro opens and 
closes the output file. 


Return value is either 0, meaning to pass non-cell records then 


to pass cell records, or SKIP_NON_CELLS to skip non-cell records. 


NOTE: this version will cause two warnings, since we use neither 
'filename' nor 'password'. You can safely ignore these 
warnings. 
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THE SAVE TRANSLATOR 
continued from page 75 


(plain text) file, with one row per 
line. Cells in a given row are 
separated by commas; empty cells 
are inserted as a pair of double 
quotes (‘”’). Labels are enclosed 
by double quotes to identify them 
as labels and to prevent any con- 
fusion that could be caused by the 
(entirely legal) presence of a 
comma within a label. 

In addition to the four required 
translator functions, FSASC.C con- 
tains the function fillin(), which 
checks for empty cells and rows 
located between the cell just 
passed to FSASC.C and the last 
cell that FSASC.C handled. fillin() 
inserts a pair of double quotes (‘”’) 
to indicate empty cells, and inserts 
blank lines for empty rows. All 
cells in a given row are separated 
by commas. 

The function init_save() just 
saves a copy of the file handle 
and returns a value of 
SKIP_NON_CELLS, telling 
Quattro that the translator only 
wants cell records. 

Since the noncell records are 
being skipped, the function 
end_nonc() won’t be called by 
Quattro and doesn’t have to do 
anything. It still must be declared, 
however, in order for the transla- 
tor to link properly. 

cvt_rec() is called once by 
Quattro for each nonempty cell. 
Quattro starts with the first (top- 
most) nonempty row and sends all 
nonempty cells (from left to right) 
in that row before moving to the 
next nonempty row. cvt_rec() calls 
fillin() to insert any empty rows or 
cells, then writes out the numeric 
value or label string. 

In this case, end_save() doesn’t 
do anything, but it needs to be 
declared so that the translator can 
be linked. 


COMPILING AND LINKING 

A file translator’s internal struc- 
ture is different from the internal 
structure of a regular .EXE file. 


Specifically, a file translator has 
different startup code and uses a 
special library (which replaces the 
regular Turbo C Runtime Library). 
To create the translator, you must 
have the Quattro Developer’s 
Toolkit, which contains all the 
files you need. 

A file translator must be com- 
piled with Turbo C’s Compact 
memory model. The startup code 
file is COSAVEC.OB] (instead of 
the regular COC.OBJ). Since the 
special library is QUATTROC.LIB, 
which contains all the I/O rou- 
tines used in FSASC.C, you don’t 
have to link in CC.LIB. If you use 
any math routines, then you 
must link in a special library, 
QMATHC.LIB, which replaces 
MATHC.LIB. 

If you’re using the Turbo C 
Integrated Environment 
(TC.EXE), you'll need to use a 
project file. For FSASC.C, create 
the file FSASC.PRJ, which con- 
tains the following: 
c:\tc\lib\cOsavec.obj 
fsasc.c 
c:\tc\lib\qe.lib 

This file presumes that your 
library directory is C:\TC\LIB; 
you may need to change this path 
to reflect your own hard disk 
setup. 

Note that when you list 
COSAVEC.OB] as the first file, 
Turbo C’s linker uses it (instead 
of COC.OB)J) as the startup code. 
Be sure to set the compiler model 
to Compact. After you compile 
and link, you'll have a file named 
FSASC.EXE. Rename it to 
FSASC.TRN, and copy it to your 
Quattro disk or directory for test- 
ing and use. 

If you’re using the Turbo C 
command-line compiler (TCC.EXE), 
compile your program to .OBJ 
code only. Use the Compact 
model and tell TCC where the 
include directory is located: 


C>tcc -c -me -Ic:\tc\include fsasc 


Invoke TLINK.EXE and tell it 
which startup code and libraries 
to use: 


C>tlink c:\tc\lib\cOsave fsasc, 
fsasc.trn,, c:\tc\lib\qe 


continued on page 78 


init_save(h, filename, password) 
unsigned h; /* file handle */ 
char *filename; /* filename -- has Pascal style length byte as 
initial byte, null-terminated */ 

unsigned password; /* password flag : 1 if one entered, 0 if not */ 
€ 

handle = h; 

return SKIP_NON_CELLS; 
> 


/* end_nonc() function 


Called after all the non-cell records have been passed. 
Return SKIP_CELLS to skip the cell records or 0 to not skip. 
e/ 


int end_nonc(void) 
€ 

return 0; 
> 


/* cvt_rec() function 


Convert given record. Called to present a worksheet record to 
the driver. The translator can either write the record information 
to disk or ignore the record. 


This procedure is passed a pointer to the worksheet record header. 
It should return a pointer to a record descriptor structure. 

On a 'save' operation the 'doserr' and 'reclen' fields are used 
to return status information to Quattro. 


The doserr field must be given one of the following status codes: 
DE_CORRUPT save the file to disk with this as the last record 
DE_ABORT do not save the file; delete it from disk 
ACCEPTED all is okay; send the next record 

*/ 
RECDESC rec; /* record descriptor to return. This must 

be external to ensure it remains in existence 

after a pointer to this structure is returned 

to Quattro. */ 


RECDESC * cvt_rec(REC_HDR *r) 
{ 


unsigned rectype; 
void *body; 


/*  qTempHeap(4*1024); /* create heap for internal translator use */ 


/* record type */ 
/* pointer to record body */ 


rectype = r->rectype; /* fetch record type */ 


rec.doserr 
rec.reclen 


ACCEPTED; 
ACCEPTED; 


body = (void *) &r->recbody; 
switch (rectype) ¢ 


/* Primary return flag says all is OK */ 
/* Secondary return flag says all is OK. */ 


/* pointer to body */ 
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case INTEGER: { 
INTEGER_REC *c = CINTEGER_REC *) body; 


fillin€ (NUMBER_REC *) c); /* typecast done 
to prevent warning */ 
sprintf (out, "%d",c->value); 
_write(handle, out, strlen(out)); 
break; 
> 


case NUMBER: { 
NUMBER_REC *c = (NUMBER_REC *) body; 


fillin(c); 
sprintf (out,"%g",c->value); 
_write(handle, out, strlen(out)); 
break; 

> 


case LABEL: { /* includes string-valued formulas */ 
LABEL_REC *c = (LABEL_REC *) body; 


fillin€ (NUMBER_REC *) c); /* typecast done 
to prevent warning */ 
/* skip leading format byte: */ 
sprintf(out,"\"%s\"",c->text+1); 
_write(handle, out, strlen(out)); 


break; 
> 
default: /* ignore WKQEOF end of file record */ 
break; 
2 
return &rec; /* return pointer to record descriptor */ 
> 


/* end_save() function 


Gives the translator the chance to close ancillary files, 
deallocate heaps, etc. 


*y, 

void end_save(void) 

€ 

/* qTempDeall(); /* release temporary memory heap */ 
return; /* There is no return value */ 

> 
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/* includes numeric-valued formulas */ 


Called after all of the records have been passed to the driver. 


THE SAVE TRANSLATOR 
continued from page 77 


The result is FSASC.TRN; copy 
this file to your Quattro disk or 
directory. 


USING A TRANSLATOR 


Using a translator is easy: just save 
a spreadsheet with the appropri- 
ate file extension. For example, 
load in the file SAMPLE.WKQ,, 
which comes on your Quattro 
disks. (Figure 2 shows a portion of 
SAMPLE.WKQ as it appears on 
your screen from within Quattro.) 
Now, save SAMPLE.WKQ to disk 
as SAMPLE.ASC, using the Save 
option on Quattro’s File menu. 
Behind the scenes, Quattro auto- 
matically looks for the save trans- 
lator file FSASC.TRN, loads it 
from disk into memory, and uses 
it to write the spreadsheet to disk 
in ASCII format. The result is an 
ASCII file that looks like the file 
in Figure 3. 

What if the appropriate file 
translator can’t be found on disk? 
Quattro then saves the file to disk 
in the standard .WKQ format. 


ADD-IN VERSATILITY 


This should give you a feeling for 
what it’s like to use the Quattro 
Developer’s Toolkit. Most of the 
add-in programs that you can 
create follow the same general 
format of a set of functions called 
by Quattro at specific times or in 
response to specific events. In 
future issues, we'll talk about how 
to write custom @ functions, as 
well as general add-in programs 
in Turbo C and Turbo Pascal. 


Bruce Webster is a computer merce- 
nary living in California. He can be 
reached via MCI MAIL (as Bruce 
Webster) or on BIX (as bwebster.) 


Listings may be downloaded from 
CompuServe as OUTRAN.ARC. 


A MEMORY-RESIDENT 
CLOCK UTILITY 


No matter what else your PC is doing, it can always give you 


the time of day. 


Ron Sires 


Memory-resident utilities have taken the 
PC world by storm. Once installed, these 
programs remain in your computer’s 
memory and wait for an event that tells 
them to take action. The signal event may 
——_ be user-generated, such as striking a 
mouse button or a particular key combination; or it 
may be computer-generated, like reading a disk or 
writing to the screen. After the utility has performed 
its task, it returns to its inactive state in the comput- 
er’s memory, waiting for the signal event to occur 
again. 

The signal event is termed an interrupt, and the 
procedure that is called when the interrupt occurs is 
an interrupt service routine, or ISR. The interrupts are 
numbered from 0 to 255, and many pass control to 
ISRs in the PC ROM BIOS when they occur. A 
memory-resident program may replace a ROM BIOS 
routine with its own ISR, but a well-behaved resident 
program will save the address of the interrupt’s origi- 
nal ISR. When the interrupt is generated, the pro- 
gram will call the original ISR, after taking its own 
action. This allows more than one memory-resident 
utility to service the same interrupt. 

CLOCK.COM, a memory-resident clock utility 
application, incorporates an ISR and demonstrates 
how Turbo C makes the development of well- 
behaved memory-resident programs very easy. 
CLOCK takes over the timer control interrupt (inter- 
rupt 1CH), which the PC generates about 18.2 times 
a second. Every time this interrupt occurs, CLOCK 
inspects the system time and displays it in the upper 
right corner of the screen if the time isn’t already 
displayed there. Every time the minutes roll over to a 
new hour, the speaker beeps twice. 


WIZARD 


INSTALLING THE ISR 

The source code for CLOCK.COM is given in Listing 
1. The following global declaration in CLOCK.C 
defines oldtick as a pointer to an interrupt function 
that doesn’t return a value: 


void interrupt (*oldtick)(); 


Pointer oldtick saves the address of the timer inter- 
rupt’s original service routine. The Turbo C keyword 
interrupt causes the compiler to add ISR housekeep- 
ing code to the beginning and end of the function. 
When the function terminates, the computer returns 
to the state it was in before the function took control. 

The original ISR will be replaced by tickintr(), 
which is also declared as an interrupt function. This 
process of saving and replacing ISRs is handled by 
four lines of code from main(), shown in Figure 1. 

The number of an interrupt, in this case interrupt 
1CH, is passed to Turbo C’s getvect() function. 
getvct() returns the address of that interrupt’s cur- 
rent ISR, which is also known as the interrupt vector. 
This address is saved in oldtick. The disable() func- 
tion turns off interrupts, so that the computer doesn’t 
attempt to call the ISR before it’s completely in- 
stalled. The number of the interrupt being replaced, 
and the new ISR’s address, are passed to the 
setvect() function. Turbo C interprets the identifier 
tickintr (without the parentheses) as the address of 
the function, rather than as a call to the function. 
Finally, enable() turns the interrupts back on once 
the new ISR is completely and safely installed. 


WHAT TIME IS IT? 


The ISR tickintr() uses the Turbo C biostime() 
function to determine the time. The invocation 
biostime(0,0L) returns the number of timer ticks (in 
the form of a long integer value) that has occurred 
since system midnight. These timer ticks occur at a 
rate of 18.20648193 per second, according to IBM’s 
ROM BIOS listing. For CLOCK’s purposes, rounding 
this rate to 18.2065 ticks per second yields sufficient 
accuracy. 

continued on page 80 
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TURBO C 


CLOCK 
continued from page 79 


First, we want to convert this 
number of ticks into the number 
of minutes that have passed since 
system midnight. The formula to 
use is 


minutes since midnight = 
ticks since midnight 


18.2065 ticks/second X 60 seconds/minute 


or: 
ticks since midnight 
1,092.39 ticks/minute 


In a structured 
language such 

as C, designing a 
good data structure 
may be even more 
important than 
using a correct 
program control 


Structure. 


One major consideration in any 
memory-resident program (espe- 
cially one that executes 18.2 times 
per second!) is to use as little time 
and memory as possible. Since 
floating point arithmetic is very 
costly in terms of both time and 
memory, it’s best to use integer 
arithmetic. To perform this divi- 
sion using integers, we apply the 
mathematical fact that multiplying 
the top and bottom of a fraction 
by the same number doesn’t 
change the value of the fraction. 
The first instruction in tickintr() 
multiplies the top and bottom of 
our fraction by 100, converting 
ticks into minutes without resort- 
ing to floating point arithmetic: 
mins_aft_mid = 
(biostime(0,0L) * 100L) / 109239L; 
From this number, tickintr() 
derives rawhour, which is the 
hour on a 24-hour clock; hour, 
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oldtick = getvect(0x1C); /* Save original ISR in oldtick */ 


disable(); /* Disable interrupts. my 
setvect(Ox1C, tickintr); /* Replace ISR with tickintr() */ 
enable(); /* Allow interrupts again. */ 


Figure 1. The process of saving the old ISR interrupt vector and replacing it 


with tickintr. 


typedef struct SCR_LOC { 
char s_char, s_attr; 


} SCR_LOC; /* One screen location. =, 
typedef SCR_LOC SCRLINE[80]; /* One screen Line. */ 
SCRLINE far *scr; /* Entire screen. *7 


Figure 2. Declaration of the screen access data structures. 


MyLine[5][10].s_char = '2'; 


/* Put a 'Z' at row 5, col. 10 */ 


HomeAttr = MyLine[0][0].s_attr; /* Store the attribute of */ 
/* the upper left corner. */ 


Figure 3. Direct assignments to the video refresh buffer. 


Start Stop Length Name 
OOOOOH OOF9DH OOF9EH _TEXT 
OOFAOH 01247H OO2A8H _DATA 
01248H 0124BH O0004H _EMUSEG 
0124CH 0124DH 00002H _CRTSEG 
0124EH 0124EH OOOO0H _CVTSEG 
0124EH 0124EH OOOO0H _SCNSEG 
0124EH 01297H OOO4AH _BSS 
01298H 01298H O0O00H _BSSEND 


Class 


CODE 
DATA 
DATA 
DATA 
DATA 
DATA 
BSS 
BSSEND 


Figure 4. CLOCK’s memory usage from the map file. 


which is the hour on a 12-hour 
clock; and minute, the number 
of minutes after the hour. 


STRUCTURES AND SCREENS 


In a structured language such as 
C, designing a good data structure 
may be even more important than 
using a correct program control 
structure. A data structure that 
corresponds closely with the ob- 
ject it models makes a program 
clearer and more efficient. 
CLOCK’s method for accessing 
the display screen illustrates such 
a data structure. 

Each position on the PC’s 
screen corresponds to a pair of 
bytes in memory—the first byte is 
the ASCII code of the character, 
while the second byte is the attri- 
bute or color of the character and 
its background. Two thousand of 
these pairs exist; one pair corre- 
sponds to each location on the 25- 
row, 80-column display. These 
character-attribute pairs—called 
the video refresh buffer—begin at 
hex address B000:0000 for display 
adapters connected to a mono- 
chrome screen, or at B800:0000 
for adapters connected to a color 
screen. 


Once given the row and 
column of a character or attribute, 
CLOCK’s video access data struc- 
tures can read or write that char- 
acter or attribute at any screen 
location. For example, the struc- 
tures allow the program to easily 
put an ‘S’ at row 5, column 20; 
or to find the attribute of row 3, 
column 79. The video access data 
structures are set up in the dec- 
larations (excerpted from 
CLOCK.C) in Figure 2. 

In Figure 2, the typedef key- 
word defines a complex variable 
in a series of logical steps. Unlike 
the declaration of a variable, a 
typedef declaration does not allo- 
cate memory for a variable. In- 
stead, typedef creates a new data 
type that is equivalent to some 
usual C type. The first typedef 
declares the SCR_LOC type to be 
a structure of two bytes, where 


one byte is called s_char and the 
other is called s_attr. Thus, if 
MySpot is a variable of type 
SCR_LOC, and MySpot occupies 
the same place in video memory 
as the screen’s upper left corner, 
the character at that screen loca- 
tion is MySpot.s_char, and the 
attribute is MySpot.s_attr. The 
assignment below puts an ‘A’ at 
that screen location: 

‘Al ‘ 

The second declaration in Fig- 
ure 2 defines the SCRLINE type 
as an array of 80 SCR_LOC struc- 
tures. This array is analogous to a 
single line on the screen; how- 
ever, it comes close to meeting the 
goal of direct screen access by row 
and column because of the way C 
handles array indexing. If MyLine 
is a variable of type SCRLINE and 
is located at the beginning of 
video memory, then MyLine[0] is 
the first screen line, MyLine[1] is 
the second, and MyLine[20] is the 
21st. This works because incre- 
menting the index of an array by 
one causes the memory address 
that is accessed to be incremented 
by the szze of the array’s type. 
MyLine’s type is SCRLINE, and its 
size is equal to that of one screen 
line. This means that MyLine[1] is 
one screen line past MyLine[0] 
and MyLine[20] is 20 screen lines 
past MyLine[0]. Although this pro- 
cess accesses the screen by row, 
what about providing access to 
individual locations on that row? 
MyLine[n], where n is any integer, 
is of type SCRLINE, which means 
that it is an array of 80 SCR_LOC 
structures. A second array index, 
specifying an element number 
from 0 to 79, allows access to indi- 
vidual elements of the array. Since 
each array element is a structure, 
the structure member must also be 
named for direct access to the 
screen. Assignments such as those 
in Figure 3 then become possible. 


MySpot.s_char = 


One further puzzle, glossed 
over in the above paragraphs, 
remains to be solved. When a vari- 
able of type SCRLINE is declared, 
Turbo C allocates space in 
CLOCK’s data segment for that 
variable. In order for the screen 
access scheme to work, the vari- 
able must be located at the begin- 
ning of video memory. The only 
way to access a specific address in 
memory, such as B000:0000, is to 


Since most 
memory-resident 
programs must be 
executed as .COM 
rather than .EXE 
files, those programs 
must be compiled to 
the Tiny memory 
model. 


use a pointer. In fact, for the 
single-user, single-task PC, a 
pointer and a memory address 
are virtually the same thing. The 
final trick to accessing the video 
memory as though it were a 
25 X 80 array of character- 
attribute pairs is to declare a 
pointer to such an array, assign 
the desired memory location to 
that pointer, and then treat the 
pointer as the name of an array. 
The pointer ser is defined as a 
far pointer to SCRLINE so that 
both a segment and an offset can 
be specified. ser is given its value 
through a call in main() to Turbo 
C’s MK_FP library function (see 
“Building Far Pointers with 
MK_FP,” TURBO TECHNIX, 
March/April, 1988, p. 61.) The 
pointer takes on a value of either 
B800:0000 or B000:0000, depend- 
ing on whether or not a color dis- 
play is in use. This allows assign- 
ments to and from scr[row] 


[column].s_char and scr[row][col- 
umn].s_attr to be used for read- 
ing from and writing to the 
screen, as shown in the disptime() 
function. 


MAKING CLOCK MEMORY- 
RESIDENT 


When a normal program termi- 
nates, it gives all of its allocated 
space back to DOS. For a program 
to remain resident, it must retain 
its memory allocation after control 
returns to DOS. Turbo C provides 
this ability with the keep() func- 
tion, which takes the two integer 
parameters status and size. status 
is the exit status to be returned to 
DOS, and size is the amount of 
memory measured in paragraphs 
(one paragraph equals 16 bytes) 
that the program retains. It seems 
strange that this function requires 
that the program’s size be known 
while the program is being devel- 
oped, but there is a way around 
this requirement. 

Since most memory-resident 
programs, including CLOCK, must 
be executed as .COM files rather 
than as .EXE files, those programs 
must be compiled to the Tiny 
memory model, which puts all of 
the programs’ code and data into 
64K of memory. This means that 
CLOCK can safely be compiled 
with size = 4096, because the pro- 
gram will retain as much memory 
as it could possibly need (64K). 
However, it’s desirable for resi- 
dent programs to use as little 
memory as possible, so once the 
program has been tested and 
debugged to its final form, the 
link map is used to find the actual 
number of paragraphs that the 
program requires. The following 
command line compiles and links 
CLOCK in the Tiny memory 
model, and generates a link map 
file called CLOCK.MAP: 


tcc -mt -M clock.c 


The map file is an ASCII text file 
that contains information about 
how CLOCK’s memory will be 
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LISTING 1: CLOCK.C 


#define COPYRIGHT "CLOCK 1.0 (c) Copyright 1988, Sires Software, "\ 


Clock.c -- Memory-resident program to display a clock in the 
upper right corner of the screen 
(c) Copyright 1988, Sires Software, All Rights Reserved. 
* 


CAUTION: Do not run CLOCK from within the Turbo C integrated 
environment. The computer may hang if a memory-resident 
program is installed from within another program. 


tcc -mt -M clock.c 
exe2bin clock.exe clock.com 


To compile from command line: 
To convert .EXE to .COM file: 


"ALL Rights Reserved." 


#include <dos.h> 
#include <bios.h> 


#define TRUE -1 
#define FALSE 0 


typedef struct SCR_LOC ¢ 


> 


typedef SCR_LOC 
SCRLINE 


char s_char, s_attr; 
SCR_LOC; /* One screen location 
/* One screen line 


/* Pointer to entire screen */ 


SCRLINE [80] ; 
far *scr; 


char attr; 
void interrupt (*oldtick)(); 


void disptime(int hour, int minute, int rawhour) 


€ 


> 


int IG 


(hour > 9) 2? '1' : 
(hour % 10) + 'O'; 
Pele 

(minute / 10) + '0'; 
(minute % 10) + '0'; 


scr [0] [70] .s_char 
scr [0] [71] .s_char 
scr [0] [72].s_char 
scr [0] [73] .s_char 
ser [0] [74] .s_char 
ser(0](75].s_char = ' '; 
scr [0] [76].s_char = (rawhour < 12) ? 'A' : 'P!; 
ser(0][77].s_char = 'M'; 
for (i=70; i<78; i++) 

scr [0] [i].s_attr = attr; 
return; 


void beep(void) 


/* 


{ 


Routine will beep the speaker twice briefly. */ 
unsigned int ieee 


for (i=0; i < 2; i++) 

€ 
sound(512); /* Beep at approx. middle C 
for (j=0; j < 40000; j++) ; /* for 1/2 second. 
nosound ); /* Turn off speaker 
for (j=0; j < 20000; j++) ; /* for 1/4 second. 
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CLOCK 
continued from page 81 


allocated when CLOCK is run. 
The portion of CLOCK that per- 
tains to size is given in Figure 4. 
The last value in the Stop column 
is the number of bytes (in hex) 
used by the program. To convert 
this value to the number of para- 
graphs, just shift it one hexadec- 
imal digit to the right and round 
the last digit up. In the example, 
the number of bytes is 01298H, 
which converts to 012AH para- 
graphs (remember that in hexa- 
decimal arithmetic, 9 + 1 = A). 
Thus, the keep() function for this 
example is keep(0,0x12A). As was 
done in CLOCK, this number may 
be rounded up to err on the side 
of safety. 

In order for CLOCK to work 
properly, it must be converted 
from the .EXE file produced by 
Turbo C to a .COM file. This con- 
version is done by the EXE2BIN 
program, which comes with DOS: 


exe2bin clock.exe clock.com 


CLOCK.C’s internal arrangement, 
with main() last and all functions 
defined before they are used, is 
due to a peculiar limitation of 
EXE2BIN, which requires that the 
source code be in that format in 
order for the .EXE file to be 
converted. 


LIMITATIONS AND POSSIBLE 
ENHANCEMENTS 


CLOCK operates in text mode 
only. If you shift into graphics 
mode with CLOCK in operation, 
CLOCK’s output will not be vis- 
ible, because the text video buffer 
is at a different location from the 
graphics video buffer. 

Text editors that work directly to 
screen memory may inadvertently 
copy CLOCK’s display to other 
parts of the screen when they 
scroll the top line downward. A 
great many programs reserve the 
top line for status information, 
and CLOCK’s display may obscure 
important information. You can 
reposition CLOCK’s output simply 
by specifying a different row and 
column position. 


Because CLOCK performs 
direct screen accesses in the inter- 
est of speed, it will create video 
“snow” on an old-style IBM CGA 
display. A strategy for eliminating 


A program 
can determine if it 
is already installed 
by inspecting 
memory at some 
offset from the 
referent of interrupt 
1CH’s vector. 


this interference can be found on 
pages 79-80 of Ray Duncan’s 
excellent book, Advanced MS-DOS 
(reviewed in TURBO TECHNIX, 
March/April, 1988). Also, CLOCK 
does not check to see if a copy of 
itself is already resident and oper- 
ating. Such a check can be per- 
formed in several ways. Most 
involve inspection of the code at 
some offset from the referent of 
interrupt 1CH’s vector for a signa- 
ture consisting of the program’s 
name or some other unique string 
of bytes like SIRESCLOCK. 

This simple version of CLOCK 
works well; take the time to im- 
prove and enhance it to your own 
satisfaction. My own commercial 
product, the Sires Alarm Clock, is 
a greatly enhanced version of 
CLOCK. Turbo C handles all of 
the difficult work—the rest is up to 
your imagination. @ 


Ron Sires is president of Sires Soft- 
ware, a database consulting and soft- 
ware development firm in Berkeley, 
California. He may be reached at Sires 
Software, 2925 M.L. King, Jr. Way, 
Berkeley, California 94703. 


Listings may be downloaded from 
CompuServe as CLOCK.ARC. 


> 
return; 
} 


void interrupt tickintr(void) 

{ 
int rawhour, hour, minute; 
int mins_aft_mid; 
static mewhour=TRUE; /* Should beep() be called 


when minute == 0? */ 


/* Use 18.2065 ticks/sec */ 

/* 18.2065 ticks/sec * 60 secs/min * 100 == 109239L */ 

mins_aft_mid = (biostime(0, OL) * 100L) / 109239L; 

rawhour = mins_aft_mid / 60; 

minute = mins_aft_mid % 60; 

if (minute % 10 + 'O' != scr[0][74].s_char /* Does the time */ 
|| minute / 10 + 'O0' != scr{0] [73].s_char) /* need to be put */ 

/* on the screen? */ 

{ 

(rawhour > 12 ? (rawhour - 12) : 

(rawhour == 0 ? 12 : rawhour)); 

disptime(hour, minute, rawhour); 

if (minute == 0) 

{ 


hour = 


if (newhour) 
{ 
beep(); 
newhour = FALSE; 
2 
3 
else 
newhour = TRUE; 
> 
(*oldtick)(); 
return; 
> 


int color_adpt(void) 
/* Return 0 if monochrome adapter, 
{ 


1 if color adapter */ 


return ((biosequip() & 0x0030) != 0x0030); 
> 


main) 
{ 
puts(COPYRIGHT); 


scr = MK_FP((color_adpt() ? 0xB800 : 0xB000), 0x0000); 
attr = 


/* Clock Installation */ 

oldtick = getvect(Ox1C); /* Save original ISR in oldtick. 
disable(); /* Disable interrupts. 
setvect(Ox1C, tickintr); /* Replace ISR with tickintr(). 
enable(); /* Allow interrupts again. 
keep(0, 0x0130); /* Terminate but stay resident with exit 
/* status 0, reserving 130H paragraphs. 


((ser[0] (0].s_attr >> 4) + (scr[0] [0].s_attr << 4)) & 0x77; 
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TURBO PROLOG 


TURBO PROLOG 2.0: 
INTELLIGENT EVOLUTION 


Turbo Prolog spreads its wings as the second 


generation is born. 


Michael Floyd 


One of the most exciting aspects of work- 
ing with the Turbo languages is watching 
their evolutionary process. Like the cater- 
piller’s transformation into a butterfly, 
the Turbo languages periodically undergo 
a metamorphic process to emerge as a 
new creature. 

Turbo Prolog has undergone its first transforma- 
tion, and has emerged wearing the colors of 2.0. 
Some of the things you'll see in the new version of 
Turbo Prolog include the ability to create and manip- 
ulate multiple databases, color graphics through the 
Borland Graphics Interface (BGI), new debugging 
capabilities, conditional compilation, extensions to 
the language, a full-featured development environ- 
ment, and a new and improved manual. 

If you're a Turbo Pascal, Turbo C, or Turbo Basic 
programmer, you may be quite surprised at some of 
Turbo Prolog 2.0’s new features. If you’re already a 
Turbo Prolog programmer, you'll want to watch 
closely as this tale of evolution unfolds. 


PROGRAMMER 


THE DATABASE CONCEPT 

By far, the most significant change in Turbo Prolog 
2.0 is its handling of the database—or should I now 
say, databases. You'll notice first that there are two 
types of databases—internal and external. An inter- 
nal database corresponds to the dynamic database in 
earlier versions of Turbo Prolog. However, you can 
now have more than one internal database. The fol- 
lowing statements, for example, declare two internal 
databases: 

DATABASE - db1 


pred! 
pred2 


predN 
DATABASE -db2 

predA 

predB 


predz 
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These statements declare the db1 database with the 
database predicates pred1, pred2, and so on; and the 
db2 database with the database predicates predA, 
predB, and so on to predZ. (Database predicates 
behave just as they do in earlier versions.) 

In Turbo Prolog 2.0, built-in predicates such as 
asserta, assertz, consult, and save have been ex- 
tended to address specific databases. For example, to 
assert pred2(“fact”) into the the dbl database, make 
the following statement: 


asserta(pred2("fact"),db1) 


Another important feature to note is that Turbo 
Prolog 2.0 supports local and global databases. Our 
discussion up until now has referred to local data- 
bases, which are databases declared locally in a pro- 
gram or module. In addition to local databases, you 
can declare global databases that are shared between 
modules. In a global database declaration, the key- 
word global must preface the database keyword. 


EXTERNAL DATABASES 


External databases extend the capabilities of the 
internal database in a number of ways. First, exter- 
nal databases can be placed in conventional RAM 
(memory below 640K), in extended memory (EMS), 
or in a disk file. In addition, external databases can 
load and store data in binary form. Finally, the use 
of B+ trees in external databases allows more effi- 
cient handling of data than is possible in internal 
databases (because of an internal database’s sequen- 
tial nature). 

An external database has two parts: data items, 
which are Turbo Prolog terms stored in chains; 
and an index value that corresponds to a B+ tree. 
Chains are a way of grouping like data (terms) into 
a structure that can be referenced. There is no 
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expression 


pa Pe I = a a 


LY | 


DATABASE 1 


; Term 1 Term 2 
Chain 1 
Domain 1 Domain 2 
Ref | Ref 2 
Chain1 (Database, Chain, Term, 
Chain 2 
e 
e 
e 
Chain 3 


Figure 1. Structure of chains in the external database. 


INTELLIGENT EVOLUTION 


continued from page 84 Chains are a 


way of grouping 
like data (terms) 
into a structure that 


practical limit on the number of 
terms that a chain can contain. In 
addition, there is no limit to the 
number of chains that can be 
stored in an external database. 
Figure | shows the structure of a 


chain. can be referenced. 
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TermDomain, Reference) 


A chained item consists of the 
name of the database that con- 
tains the item, the name of the 
chain, the domain that the chain 
belongs to, the actual term in the 
chain, and a special reference 
value that allows quick lookups 
within the chain. 

As an example, imagine a case 
where you have a database that 
tracks the PCs in a company. One 
chain could correspond to the 


individuals in the company, and 
another chain could contain spe- 
cific information about individual 
PCs. By linking these chains to- 
gether through their reference 
values, you can easily add a rela- 
tional capability to the databases. 

The second part of an external 
database is a reference to a B+ 
tree. In Turbo Prolog, a B+ tree is 
a data structure that is contained 
in an external database. Each 
entry in the B+ tree consists of a 
key string and a database refer- 
ence number. When creating a 
new database entry, the pro- 
grammer defines a key string that 
can be referenced during lookups. 
The database reference number is 
created by Turbo Prolog as each 
entry is created, and can also be 
referenced directly. When search- 
ing for a record, the programmer 
references the key string to be 
searched on, and Turbo Prolog 
returns the associated reference 
number. This reference number is 
then used to retrieve the actual 
record from the database. 


BGI 


If you haven't seen the Borland 
Graphics Interface (BGI) in Turbo 
Pascal 4.0 or Turbo C 1.5, you’re 
in for a real treat. The BGI is a 
library of graphics routines that 
does everything from drawing spe- 
cialized character fonts to detect- 
ing the type of graphics card 
installed in your PC. The library 
includes high-level routines to 
draw lines, circles, ellipses, arcs, 
rectangles, and polygons. The 
library also contains a number of 
routines for drawing two- and 
three-dimensional bars, and pie 
slices for creating charts. In addi- 
tion, the BGI provides a number 
of patterns that can be used to fill 
any object. (For a complete dis- 
cussion of the Borland Graphics 
Interface, see “Meet the BGI,” 
elsewhere in this issue.) 


The BGI’s sixty or so graphics 
routines are accessed through 
built-in predicates. For instance, 
drawing a circle is a simple matter 
of specifying the X and Y coordi- 
nates and the radius of the circle 
in the following call: 


circle(X,Y,R) 


The BGI’s coordinate system is 
similar to the system used in the 
turtle graphics of Turbo Prolog 
1.x, although the scaling has 
changed. The upper left corner 
of the screen is designated as 
(0,0). The X (row) and Y (column) 
values increment from that point 
according to the screen mode the 
system is in. For instance, on a 


One interesting 
new feature is that 
predicates can now 
have multiple ari- 
ties. The program- 
mer simply makes 
a declaration for 
each arity that will 
be supported by a 
program. 


CGA system in low-resolution 
mode (320 X 200, four colors), the 
bottom right corner is designated 
as (319,199). Figure 2 shows the 
coordinate system used for a CGA 
in low-resolution mode. 

The BGI also supports the 
notion of viewports. As the name 
implies, a viewport is a window to a 
(possibly) larger graphics image. 
Viewports use a clipping system so 
that portions of the image that are 
not in the current viewport (or 
window) are not visible (i.e., 
clipped). 

The BGI routines allow you to 
draw either bit-mapped or stroked 
fonts. Bit-mapped fonts are gener- 


ated as an 8 X 8 matrix of pixels. 
Bit-mapped fonts are quicker to 
draw, since they are drawn pixel 
by pixel. To create larger bit- 
mapped fonts, however, the 
matrix must be multiplied by a 
scaling factor—this results in 
poorer resolution since the font 
is, in effect, magnified. 

A stroked font, on the other 
hand, is defined by a set of vectors 
that describes each character. 
Since these vectors must be inter- 
preted, they are slower to draw. 
On the positive side, stroked fonts 
retain their resolution for larger 
characters. 

The best news for Turbo Prolog 
programmers is the BGI’s drivers. 
These drivers support the 
Hercules, CGA, MCGA, EGA, and 
VGA cards, as well as the IBM 
3270 and AT&T 400-line graphics 
cards. No longer does the pro- 
grammer have to resort to C or 
assembly language for such 
support. 


LANGUAGE EXTENSIONS 


Borland has the reputation of 
listening to its customers and im- 
plementing their suggestions in 
future versions of products. Turbo 
Prolog 2.0 is no exception. Many 
enhancements to the language 
resulted directly from user sugges- 
tions. Some of these enhance- 
ments are changes to existing 
built-in predicates, while others 
are new predicates and compiler 
directives. The list of enhance- 
ments is quite long, so I'll just 
highlight some of the major 
points. 

One interesting new feature is 
that predicates can now have mul- 
tiple arities. The programmer 
simply makes a declaration for 
each arity that will be supported 
by the program. For example, 
consider the following program 
fragment: 
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(0,0) 


(319,0) 


(0,199) 


(399,199) 


Figure 2. Coordinate system for a CGA system. 
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predicates 
run 
run(integer) 


clauses 

run:- 

makewindow(1,2,3,"",0,0,25,80), 

run(0). 

run(X):- 

X <= 100, 

Y = X+1, 

write(Y), 

runcY). 
Notice that the first run clause has 
an arity of 0 (referred to as run/0) 
while the second run clause has 
an arity of 1 (run/1). Also notice 
that it is possible to call one clause 
from the other. 

Another enhancement is condi- 
tional compilation, which com- 
piles a given section of a program 
only if a condition is satisfied. 
Conditional compilation is partic- 
ularly useful for generating differ- 
ent versions of the same program. 
The syntax takes the form: 


ifdef ConstantID 
elsedef 
endef 
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For instance, we can write a rou- 
tine to set the graphics mode, 
based on the type of graphics card 
installed in the PC: 


predicates 


constants 
egaCard = 1 


ifdef egaCard 
goal 
graphics(5,1,1), 
write("System in EGA Mode), 
elsedef 
goal 
graphics(1,1,1), 
write("System in CGA Mode"), 
enddef 
This program fragment demon- 
strates another new feature—con- 
stants. As in other languages, 
once the value of the constant 
has been set, it remains the same 
throughout the program. 

Turbo Prolog 2.0 has a number 
of new window-handling features, 
including the ability to change 
window colors during program 
execution. The user of a program 
can now modify window color and 
size at runtime. 


Other features include built-in 
error handling and reporting, 
extended text mode handling, 
character manipulation similar to 
already existing built-in string 
manipulation, and more. 


THE DEVELOPMENT 
ENVIRONMENT 

Turbo Prolog’s windowed develop- 
ment environment, in a sense, has 
served as the prototype for Turbo 
Basic, Turbo C, and Turbo Pascal 
4.0, and is now a Borland stan- 
dard. Many of the changes in the 
Turbo Prolog 2.0 development 
environment were made to bring 
it more into line with the other 
Borland compiler environments. 
Now, if you’re familiar with one 
Borland development environ- 
ment, you are familiar with them 
all. 


Many of the 
changes in the 
Turbo Prolog 2.0 
development envi- 
ronment were made 
to bring it more into 
line with the other 
Borland compiler 
environments. 


Notice, for example, that most 
of the hot keys that perform 
actions such as running a pro- 
gram from the editor (Alt-R), or 
exiting from the development 
environment (Alt-X), have been 
standardized. I typically shift from 
Turbo C to Turbo Prolog (espe- 
cially in a joint development) and 
couldn’t survive without this kind 
of standardization. If you prefer 
other assignments, you can rede- 
fine the hot keys easily from 
within the environment. 


When starting up Turbo Prolog 
2.0, you’re immediately placed in 
the editor, ready to program. 
“But,” you say, “I wanted to load 
in a program first.” No problem— 
Turbo Prolog (along with all 
of the compilers) now takes 
command-line arguments. For 
instance, to load MYPROG.PRO 
into the environment upon start- 
up, simply issue the following 
command at the DOS prompt: 


PROLOG -E MYPROG 


As you go through the pulldown 
menus, notice that the Files pull- 
down menu has been moved to 
the far left. If you’ve worked with 
Turbo Pascal 4.0, Turbo C, or 
Turbo Basic, this standard menu 
will be familiar to you. For in- 
stance, when browsing for files 
using the Load option, you can 
now easily move from one direc- 
tory to another by highlighting 
and selecting the appropriate 
directory name. 

Next in the pulldown menu sys- 
tem are the Edit and Run buttons. 
As always, the Run option com- 
piles your program to memory 
and then executes that program. 
This provides the power of a com- 
piler, combined with the instant 
feedback normally seen only in 
interpreters. 

New to Turbo Prolog is the abil- 
ity to set up linker options in the 
environment. Particularly useful is 
the ability to include libraries in 
the link command. Thus, modules 
written in other languages that 
require their own runtime library 
support can now be linked in 
directly from the development 
environment. 

In addition, you have complete 
control over other options, includ- 
ing compiler directives from with- 
in the development environment. 
The programmer can set up op- 
tions without hard coding them 
into the program. Some of the 
new compiler directives allow bet- 
ter control over heap, stack, code, 
and trail sizes, overflow checking, 
and the generation of error and 
warning messages. 


DOCUMENTATION 

Unlike many compiler manuals, 
the Turbo Prolog Owner’s Handbook 
includes a complete language 
tutorial. This tutorial is a must for 
a language like Turbo Prolog, 
which is a new area for even sea- 
soned programmers. While the 
original Turbo Prolog Owner’s 
Handbook was just under 250 


Modules written 
in other languages 
that require their 
own runtime 
library support can 
now be linked in 
directly from the 
development 


environment. 


pages, the tutorial section alone in 
2.0 is now around 300 pages. The 
tutorial takes the reader through 
the Prolog language, step by 

step, and includes programming 
exercises to test the reader’s un- 
derstanding. Solutions to the 
exercises are provided. 

The manual also discusses 
other topics such as the BGI, data- 
base programming techniques, 
system-level programming, and so 
forth. In general, the reader will 
find excellent coverage of each 
topic, plus many more example 
programs. 

The reference section of the 
manual provides a quick lookup 
to all of Turbo Prolog’s built-in 
predicates. This section has been 
expanded to include full descrip- 
tions of the predicates and 
includes example programs for 


each. These example programs 
show how a particular predicate 
works, and give the reader a feel 
for the predicate’s application. 


THE SECOND GENERATION 
IS HERE 


Prolog has long been known as 

a prototyping language because 
applications can be quickly 
modeled in the language. Since 
Prolog programs provide a logical 
description of a problem, the 
prototype served as a program 
specification in the development 
process. After setting up working 
models in Turbo Prolog, program- 
mers usually developed their proj- 
ects in a language such as C. But 
with the extensions added by the 
Turbo flavor, many developers 
find that once the prototype is 
done, so is the project. 

Turbo Prolog 2.0 adds many 
features (such as conditional com- 
pilation) that previously were seen 
only in languages such as Pascal 
and C. The development environ- 
ment provides total control over 
compiler directives so that various 
versions of a program can be cus- 
tomized. Turbo Prolog 2.0 extends 
the Prolog database concept sig- 
nificantly with the implementation 
of chained terms to add true rela- 
tional capability, and the addition 
of B+ trees to allow sorting and 
retrieval of data at lightning 
speeds. In addition, with tools 
such as the BGI at your command, 
adding sophisticated graphics is a 
snap. 

The evolution of Turbo Prolog 
puts the power of Artificial Intelli- 
gence in your hands. The exten- 
sions to Turbo Prolog add power 
to traditional applications as well. 
Because of its declarative nature, 
Turbo Prolog allows you to write 
many applications in only one- 
tenth the lines of code usually 
required with traditional lan- 
guages. This difference translates 
into savings in development time, 
and ultimately reduces cost. Now, 
the only question is whether you 
want to become a conscious part 
of Turbo Prolog’s evolution ... 
and the answer should be easy. @ 
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WHAT'S IN A LIST? 


In list processing, a little bit of recursion goes a long way. 


Keith Weiskamp 


One of the powerful features of Turbo 
Prolog—a feature that gives Turbo Prolog 
the edge over its more procedural cous- 
ins, such as Turbo C or Turbo Pascal—is 
its ability to easily process lists. When 
SQUARE ONE — you're programming in Turbo Prolog, you 
don’t have to worry about all of the traditional pro- 
gramming headaches like pointers, memory alloca- 
tion, and the linked-list data structures from comput- 
er science 101. Of course, the trade-off in Turbo 
Prolog is that you have to master recursion. 

In this article, we'll explore the fundamentals of 
list processing and recursion in Turbo Prolog. We'll 
also build some useful tools to show you how to work 
with lists in Turbo Prolog. 


SQUARE ONE 


STARTING WITH THE BASICS 


Most programming languages provide some type of 
data structure, such as an array, for list representa- 
tion. The limitation of such built-in data structures is 
that they don’t allow you to construct dynamic lists— 
lists that can grow and shrink during the execution 
of a program. Fortunately, Turbo Prolog provides 
real dynamic list processing capabilities. 

A list in Turbo Prolog is simply a sequence of zero 
or more elements. Because a list is a dynamic struc- 
ture, you don’t have to specify its size. Lists are easy 
to represent in Turbo Prolog. (They are so easy, in 
fact, that you might feel a little guilty about using 
them!) A list is constructed by enclosing elements 
between the brackets [ ] as shown: 

(1,2,3,4] 

Cone, two, three, four] 

["one", "two", "three", "four"] 

( 
A comma separates each element in the list. If you 
forget a comma, the compiler gives you a friendly 
reminder. Note that we represent an empty list by 
using just the brackets []. 
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Each element or member in a list can be defined as 
either a standard domain type, such as an integer or 
a character, or a user-defined domain type. Keep in 
mind, however, that Turbo Prolog places one impor- 
tant restriction on list elements: all of the elements 
in a list must be of the same domain type. Therefore, 
the following lists aren’t valid: 

["one","two",3,4] 

[5.7,10.9,20,'c'] 

We can handle lists containing elements of different 
types through the use of complex objects. That sub- 
ject, however, is beyond the scope of this article. 

Now that you know what a list looks like, you’re 
probably wondering how to declare one. Like all 
user-defined domain types, lists must be declared in 
the domains section of a program. To declare a list 
domain, use the * symbol to indicate that the speci- 
fied domain name represents a list. For example, the 
following declaration creates a domain called strlist, 
which is defined as a list of strings: 
domains 

strlist = string* 
This domain can then be used in a predicate decla- 
ration such as: 
predicates 

search(strlist,string, integer) 
Given this declaration, the predicate search accepts 
arguments like: 
search( ["door", "window" ,"wall"], 


"door", Pos) 
search([],"wall",Pos) 


PROCESSING A LIST 


When processing a list, one of the first things to do is 
access a single element in the list. In order to do 

this, Turbo Prolog divides a list into two components, 
a head and a tail. The head is the first element in the 


list; the tail is the list that is left 
when the first element (the head) 
is removed. The symbol! is used 
to separate the head and the tail. 
As an example, let’s attempt to 
match the list [1,2,3,4] with the 
terms: 


(H|T) 
We get the following result: 
H=1 
T= [2,3,4] 
The task of dividing a list into a 
head and a tail is handled by 
Turbo Prolog’s built-in unification 
algorithm. For example, let’s de- 
fine a predicate and clause 
head_tail as: 
domains 

strlist = string* 


predicates 
head_tail(strlst) 


clauses 

head_tail( [Head|Tail). 
Now, we call head_tail with the 
goal: 
head_tail(["red","green", "blue"] ). 


Upon execution, the list 
[“red”,“green”,“blue”] is passed to 
the head_tail clause. Because the 
variables Head and Tail are uwnin- 
stantiated (i.e, have no value), 
Turbo Prolog binds (assigns) the 
first element of the list to Head, 
and assigns the rest of the list to 
Tail. In this case, the string red is 
bound to the term Head, and the 
list [“green”, “blue”] is bound to 
the term Tail. Here’s a quick pro- 
gram that applies the head/tail 
relationship: 


domains 
slist = symbol* 

predicates 
div_list(slist) 


clauses 
div_list( [Head|Tail]):- 
write("\nThe first element is: ", 
Head), 
write("The rest of the list is: ", 
Tail). 


div_list simply displays the two 
components of a list, the head 
and the tail. Let’s give the goal: 
div_list(({this,is,a,list]). 
In this case, Turbo Prolog 
responds with: 
The first element is: this 
The rest of the list is: 

c"* j s" ; tau A " l ist") 

Lists behave differently depend- 
ing upon whether the head and 
tail are bound or free, and how 
the list is passed. For instance, our 
last example removes the head 
from a list. We add an element to 
a list by instantiating the head of 
the list. Consider the following 
clause, which writes a list to the 
screen: 


domains 


intlist = integer* 


predicates 
add_elem(integer, intlist, intlist) 


clauses 
add_elem(Element, List1,List2):- 
Lists2 = [Element|List1]. 


Now, let’s give the goal: 
add_elem(1, [2,3,4],X). 

Turbo Prolog responds with: 

X = (1,2,3,4] 

When specifying a head/tail rela- 
tionship, the rule is: If the head is 
bound to a value, that value is 
added to the front of the list; if 
the head of the list is a free vari- 
able, that variable is bound to the 
first element in the list. 


A LITTLE BIT OF RECURSION 


In Turbo Prolog, recursion is used 
to perform most of the useful list 
processing tasks. After all, most list 
operations—such as finding a 
member in a list, or counting the 
number of elements in a list— 
require some method of stepping 
through a list. The typical method 
in a procedural language like C is 
a loop. In Turbo Prolog, we rely 
upon recursion or backtracking to 
handle looping. 

To show how recursion is used 
to access a list, let’s modify our 
previous clause, div_list, so that we 
can step through a complete list. 
Here is the new version: 


domains 
ilist = integer* 


predicates 
div_list(ilist) 


clauses 
div_list([]). 
div_list( [Head|Tail]):- 
write("\nThe first element is: " 
,Head),nl, 
write("The rest of the list is: ", 
Tail), 

div_list(Tail). 
Note that div_list now has two 
clauses. The first clause, which is 
known as an anchor clause, simply 
tests for the empty list. This clause 
terminates the recursion when we 
get to the end of the list. The sec- 
ond clause, which performs the 
actual processing, separates the 
head from the tail of the list and 
then displays both the head and 
the tail on the screen. Finally, 
div_list calls itself (the recursive 
call) with the tail of the list. There- 
fore, each time div_list is called, 
the list is reduced by one ele- 
ment—the current head. Each 
time the recursive call is made, 
the first div_list clause tests to see 
if the list is empty ({]). If the list is 
empty, this clause succeeds and 
we are done. For example, let’s 
call div_list with: 


div_list((1,2,3]). 


The goal produces the following 
output: 


The 
The 
The 
The 
The 
The 


first element is: 1 
rest of the list is: 
first element is: 2 
rest of the list is: 
first element is: 3 
rest of the list is: 0] 


BUILDING LIST TOOLS 


The basic recursive technique 
illustrated in the previous example 
can easily be applied to construct 
the fundamental list processing 
operations such as appending ele- 
ments, searching for elements, 
and deleting elements. To show 
you the power of Turbo Prolog’s 


[2,3] 
[3] 
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/* get an element at specified position */ 


domains 
ilist = integer* 


predicates 
index(ilist, integer, integer) 
clauses 
index( [Head |_], 1, Head). 
index({_|Tail], Pos, Elem) :- 
Pos) St. 
New_pos = Pos - 1, 
index(Tail, New_pos, Elem). 
/* The Append Tool */ 
domains 
clist = char* 
ilist = integer* 
rlist = real* 
stlist = string* 
slist = symbol* 
predicates 
append( clist, clist, clist ) /* Append 2 character lists. */ 
append( ilist, ilist, ilist ) /* Append 2 integer lists. */ 
append( rlist, rlist, rlist ) /* Append 2 real lists. */ 
append( stlist, stlist, stlist ) /* Append 2 string lists. */ 
append( slist, slist, slist ) /* Append 2 symbol lists. */ 
clauses 


append([ ], List, List ). 


append([ Head | List1 ], List2, [ Head | Rest ] ) :- 
append( List1, List2, Rest ). 


/* The Reverse Tool */ 

include "append.pro" 

predicates 
reverse( clist, clist ) /* Reverse the character list. */ 
reverse( ilist, ilist ) /* Reverse the integer list. */ 
reverse( rlist, rlist ) /* Reverse the real list.*/ 
reverse( stlist, stlist ) /* Reverse the string list. */ 
reverse( slist, slist ) /* Reverse the symbol list. */ 

clauses 
reversec [ J, £1 d- 
reverse( [ Head | Tail ], Result ) :- 


reverse( Tail, Temp ), 
append( Temp, [ Head ], Result ). 
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WHAT?’S IN A LIST? 
continued from page 91 


list processing capabilities, let’s 
construct some list processing 
tools. 

The first tool, called index, is 
shown in Listing 1. This predicate 
determines which element is at a 
specified position in a list, and in 
one respect, illustrates how a list 
in Turbo Prolog can be accessed 
like an array. index takes three 
arguments: 


index(List,Pos,Member ) 


The first argument, List, supplies 
the list to be searched. In our 
example, this argument must be a 
list of integers; you can also 
modify List to support lists of 
other domain types, such as 
strings and characters. The argu- 
ment Pos specifies the position of 
the element to be accessed, and 
Member is used to return the ele- 
ment. For example, the following 
goal binds the variable X to the 
list element 76: 

index( (20,45, 76,89] ,3,X). 


This produces the same effect as 
does the following statement, 
which is written in Turbo Pascal: 


X := List(3]; 


Of course, in order to access 
the list in Turbo Prolog, we must 
use recursion. Note that the predi- 
cate index contains two clauses. 
The first clause terminates the 
recursion, and the second clause 
decrements the list index and calls 
itself recursively until the desired 
index position is reached. 

The next tool that we'll con- 
struct is append, which is also 
shown in Listing 1. This predicate 
joins two lists together and pro- 
duces a new list. The general for- 
mat for append is: 


append(List1,List2,List3) 


Here, the arguments Listl and 
List2 provide two lists of any stan- 
dard domain type, which can be 
joined to create a new list that is 
bound to the variable argument 


List3. For example, to combine 
the list [a,b,c] with [d,e,f], we give 
the goal: 


append( [a,b,c], [d,e,f]l, L) 


In this case, Turbo Prolog 

responds with: 

L = [a,b,c,d,e, f] 

The append predicate first copies 

one element at a time from Listl 

to List3. This step is performed by 

the clause: 

append( [Head|List1],List2, 

[Head|Rest] ):- 

append(List1,List2,Rest). 

Each time append calls itself, the 

current first element (Head) of 

List] becomes the first element of 

List3. This process continues until 

Listl is empty. The following an- 

chor clause terminates the recur- 

sion: 

append([],List,List ). 

This anchor clause also makes 

sure that List2 is joined with List3. 

How is this done? Well, remember 

that List3 is represented as the 

two components: 


[Head|Rest] 


Therefore, when the recursion 
terminates, the term Rest is bound 
to the second list. 

The last tool provided in Listing 
1 illustrates how the append predi- 
cate can be used to alter the order 
of a list. In this case, the predicate 
reverse is used to reverse a list. 
For example, let’s give the goal: 
reverse([1,2,3,4],L). 
This goal produces the result: 
L = [4,2,3,1) 
It’s easy to reverse a list by using 
recursion. The technique involves 
stepping through the list by allow- 
ing the second reverse clause to 
call itself, as shown below: 
reverse( [Head|Tail] ,Result):- 

reverse(Tail,Temp), 
append( Temp, [Head] ,Result). 

When the list becomes empty, the 
recursion is terminated by the 
clause: 


reverse([],[]). 


Once the list becomes empty, the 
new list is created by appending 
elements in the reverse order 


from which they were removed. 
To help you see how this is done, 
let’s trace through the reverse 
predicate using the list [1,2,3,4] as 
the first argument. Each time 
reverse calls itself, the list is separ- 
ated as shown: 


Call 1: 
Head = 1 
Tail = (2,3,4] 
Call 2: 
Head = 2 
Tail = [3,4] 
Calil3- 
Head = 3 
Tail = [4] 
Call 4: 
Head = 4 
Tail = 0) 


At this point, the list is empty and 
the first clause terminates the 
recursion. Therefore, the next 
step consists of the following calls 
to append to construct a new list: 
append( [],4,Result) 

append( [4] ,3,Result) 

append( [4,3] ,2,Result) 

append( [4,3,2],1,Result) 
Although the append predicates 
are listed together, they are actu- 
ally called each time the recursion 
unwinds one level. Remember 
that reverse called itself recur- 


sively four times in order to get to 
the end of the list. Therefore, 
when the recursion stops, it must 
unwind one level at a time. 


END OF THE TOUR 


This concludes our quick tour of 
Turbo Prolog’s list processing 
capabilities. We started with the 
fundamentals of list construction 
techniques, and then wrote a few 
predicates to illustrate how lists 
can be processed with Turbo 
Prolog. Along the way, we’ve 
investigated most of the basic 
techniques for writing recursive 
clauses. The key to writing useful 
list processing predicates in Turbo 
Prolog lies in using recursive pro- 
gramming techniques. @ 
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TURBO PROLOG 


PLAYING CAT AND MOUSE 
IN TURBO PROLOG 


Don’t grab your mouse by the recursive tail just yet! 


You may need to backtrack. 


Safaa H. Hashim 


When you pursue a mouse with Turbo 
Prolog, you'll find that the game is very 
different from a mouse chase in Turbo C 
and Turbo Pascal. The fine art of pro- 
gramming a mouse in Turbo Prolog is the 
=_—_— topic of this first article in a two-part se- 
ries. In Part 2, I'll show how you can use these 
mouse programming techniques to capture the 
power of your mouse for various Turbo Prolog 
applications. 

We won’t explore the basics of mouse program- 
ming in this discussion, because they are thoroughly 
covered in Kent Porter’s article “Mouse Mysteries,” 
elsewhere in this issue. I highly recommend that you 
read “Mouse Mysteries” before you jump into Turbo 
Prolog’s cat-and-mouse techniques. Particularly 
important are the sections on mouse functions and 
how to communicate with the mouse. 

This article deals specifically with the Microsoft 
Mouse. If you use a different mouse, don’t worry— 
most mouse packages contain a driver that emulates 
the Microsoft Mouse driver. 


BUILDING THE BETTER MOUSE TRAP 

As discussed in “Mouse Mysteries,” the driver for the 
Microsoft Mouse uses a software interrupt for com- 
municating between the mouse and the computer. 


WIZARD 
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To return the mouse status, for example, we execute 
interrupt 33H (51 decimal) and make a call to func- 
tion 0. This call resets the serial port of the mouse, 
and sets the internal driver variables to their initial 
values. Thus, in order to communicate with the 
mouse, we must be able to make DOS interrupt calls 
using Turbo Prolog. 
Turbo Prolog does not support inline 
assembler for interrupt calls, but instead 

provides the built-in predicate bios. 
The bios predicate lets you make 
calls to the ROM BIOS, including 
the interrupt service routines. The 

bios predicate takes three 

arguments. The first 
argument 
refers to 
the interrupt 
number being 
called, and the last 
two arguments refer to compound objects corre- 
sponding to the registers before and after the bios 
call. The general form of the bios predicate is: 
bios(InterruptNo,RegistersIn, 

RegistersOut) 

Internally, Turbo Prolog defines a special domain, 
called the reg domain, for RegistersIn and 
RegistersOut. The reg domain takes the form: 


reg(AX,BX,CX,DX,SI,DI,DS,ES) 


The arguments of the reg domain represent eight 
16-bit 8088 registers. We use these registers to pass 


parameters to an interrupt service 
(RegistersIn), as well as to return 
the result of the execution of that 
service (RegistersOut). 

To see how the bios predicate 
works in relation to the mouse, 
let’s consider an example. Listing 
1 defines two clauses: One clause 
checks to see if the mouse is 
installed; the other clause initial- 
izes the mouse. To see how Listing 
1 reacts to different situations, 
enter the following goal before 
and after installing your mouse 
driver: 


Goal: msm_chk_init(STATUS) 


Note in Listing 1 that the first call 
in msm_chk_init is a bios call to 
interrupt 33H (the $ indicates a 
hex value). We must specify the 
function call (in this case, 0) in 
the AX register, so the first argu- 
ment of reg (for the input regis- 
ters) is set to 0. This call does not 
use the other registers. However, 
since the domain has an input 
flow pattern, Turbo Prolog re- 
quires that the entire domain be 
instantiated. Therefore, the other 
seven register slots are padded 
with 0s. 

The status value is returned 
back in the AX register, so we 
specify the variable AX in the first 
slot of the output registers. Again, 
we're not concerned with the oth- 
er registers, so we’ve used the 
anonymous variable (_). 

After making the bios call, 
msm_chk_init calls 
report_init_status, which reports 
whether or not the mouse is 
installed. 

Using the same principles 
described in Listing 1| for initializ- 

ing the mouse, we can write 

other clauses to call all of 
the driver functions. 
Listing 2 documents 


continued on page 96 


LISTING 1: INIT.PRO 


/* 
A program to check for the initial mouse state 


by & 


PREDICATES 
msm_init /* MicroSoft Mouse initialization predicate */ 
msm_chk_init(STRING) /* Check initial mouse state */ 
report_init_status( INTEGER, STRING) 


CLAUSES 
msm_init :- 
bios($33, reg(0,0,0,0,0,0,0,0), 


AX <> 0. 


msm_chk_init(STATUS) :- 
bios(51, reg(0,0,0,0,0,0,0,0), 


report_init_status(0,"Mouse is not installed"). 
report_init_status(-1,"Mouse is installed"). 


LISTING 2: MSM-DRV.PRO 


/* HHH EERE ERIKA EIK KIKI 


Microsoft Mouse Driver (functions) Predicates 
Safaa H. Hashim 


Works with MicroSoft's Driver and with MOUSE 
SYSTEMS driver for their PC MOUSE driver 
(MSMOUSE . COM) . 


This program is a modified version of a program by 
Terry Dawson. 


HEREEKKEKRERREREERRERRERER ERE EEE EKER EERE */ 


PREDICATES 
msm_init 
msm_show 
msm_hide 
msm_stat( INTEGER, INTEGER, INTEGER) 
msm_pos( INTEGER, INTEGER) 
msm_press( INTEGER, INTEGER, INTEGER, INTEGER, INTEGER) 
msm_release( INTEGER, INTEGER, INTEGER, INTEGER, INTEGER) 
msm_horz( INTEGER, INTEGER) 
msm_vert( INTEGER, INTEGER) 
msm_block( INTEGER, INTEGER, INTEGER) 
msm_text( INTEGER, INTEGER, INTEGER) 


May/June 1988 TURBO TE@ 


CAT AND MOUSE 


continued from page 95 
msm_mickey( INTEGER, INTEGER) 
msm_user( INTEGER, INTEGER) the various function calls to the 
msm_pen_on mouse. Again, “Mouse Mysteries” 
nee per ott rovides a detailed explanation of 
msm_ratio( INTEGER, INTEGER) P J P 
msm_cond( INTEGER, INTEGER, INTEGER, INTEGER) each function call. 
msm_ds( INTEGER) 
PROGRAMMING TECHNIQUES 
CLAUSES Once the basic calls have been 
/* MSMOUSE FUNCTION # 0 */ implemented, we're ready to use 
them in our applications. First, we 
msm_init:- must determine how to continu- 
bios($33,reg(0,0,0,0,0,0,0,0), ously poll the mouse. Our initial 
inclination might be to embed the 
AX<>0. ; ae S 
function calls within a recursive 
MSMOUSE FUNCTION # 1 */ loop. However, even with Turbo 
Prolog’s tail recursion optimization 
msm_show: - techniques (see “The Tail Recur- 


Binecsss, reget 0;0,0,0,0,0,0), sion Tiger,” TURBO TECHNIX 


January/February, 1988) your pro- 
MSMOUSE FUNCTION # 2 */ gram will quickly run out of stack 
space, and will end abruptly with 
a runtime error. Therefore, the 
solution is to use a repeat/ fail 
loop, which reclaims stack space 
MSMOUSE FUNCTION # 3 */ after each pass. Listing 3 uses a 
repeat/ fail combination to poll 
the mouse and to report the last 


msm_hide: - 
bios($33,reg(2,0,0,0,0,0,0,0), 


msm_stat(Button,Row,Col):- /* (0,0,0) */ 
bios($33,reg(3,0,0,0,0,0,0,0), 


reg(_,BX,CX,DX, , ,,_)), button pressed. The loop occurs 
Button=BX, Col=CX, Row=DX. in the button_status clause: 
MSMOUSE FUNCTION # 4 */ button_stetus: =~ 
msm_init, 
msm_pos(Row, Col) :- PAI)! OF pots Na 
7 ’ 
bios($33,reg(4,Col,Row,0,0,0,0,0), msm stat(X,_,_), 
button(X,_). 
MSMOUSE FUNCTION # 5 */ The call to button(X,_) provides 


the failing condition. If a button 
has not been pressed, button(X,_) 


/* Flow pattern: (1,0,0,0,0) */ 
msm_press(Button, Status, Count, Row, Col): - : . 
bios($33, reg(5,Button,0,0,0,0,0,0), fails and the clause backtracks to 


reg(AX,BX,CX,DX,_,_,_,_)), repeat, starting the polling pro- 
Status=AX, Count=BX, Col=CX, Row=DX. cess over. 


To run Listing 3, issue the goal: 


MSMOUSE FUNCTION # 6 */ 


Goal: button_status. 
* Flow pattern: (i,0,0 * Peer yrEs, 6 

ee etemeaien: ay Bak: Row, Col):- After die snquse is initialized 

bios($33,reg(6,Button,0,0,0,0,0,0), (msm_init) and its cursor is dis- 

reg(AX,BX,CX,DX,_,_,_._)), played (msm_show), the program 

Status=AX, Count=BX, Col=CX, Row=DX. enters the repeat loop. The call to 
msm_stat binds the variable X to 
an integer value that refers to the 
msm_horz(Min,Max) :- /* Gi,i) */ number of the pressed button. If 

bios($33,reg(7,0,Min,Max,0,0,0,0), no button is pressed, the returned 
value is 0. X is then passed on to 
button, which checks to see if a 
button has actually been pressed 
(X <> 0). button then uses 
Bmeaning to report the name of 
the pressed button. As mentioned 
earlier, if no button has been 
pressed, button fails and back- 
tracks to repeat. When a button is 
pressed, button succeeds and the 
program terminates. 


MSMOUSE FUNCTION # 7 */ 


96 TURBO TECHNIX May/June 1988 


We can expand the techniques 
in Listing 3 to allow the continu- 
ous use of the mouse, even after 
we have pressed a button. This 
approach is handy in an applica- 
tion that uses the mouse for con- 
tinuous interaction with the user. 
We do this by appending a fail to 
the end of the button clause: 
button(X,Y) :- 

X <> 0, /* When X=0 then no 
button is pressed */ 
Bmeaning(X,Y), 
write("\n",Y,"\n"), 
fail. 
This guarantees that button 
will always fail and that the pro- 
gram will backtrack to repeat (in 
button_status), starting the whole 
process over again. In this case, 
the only way to stop the program 
is to use the Ctrl-Break sequence. 

Another useful Turbo Prolog 
predicate reports the cursor posi- 
tion at the click of a particular 
mouse button. POSITION.PRO 
(Listing 4) is an example of this 
“reporting” technique. To invoke 
POSITION.PRO, issue the goal: 


Goal: report_pos 


The system then enters text mode, 
which is the default mode; now 
you can move the cursor with the 
mouse. When you press the left 
button, the program writes the 
row and column of the cursor 
position. When you move the cur- 
sor to a new position and press 
the left button again, the program 
writes the new row and column 
values. This continues each time 
you press the left button. When 
you press the right button, the 
screen changes into graphics 
mode and displays the graphics 
cursor (an arrow). If you press the 
left button now, the X and Y coor- 
dinates of the cursor are repre- 
sented as an integer between 0 
and 31999 (the range of 0-31999 is 
the coordinate system used by 
Turbo Prolog in graphics mode). 
Notice two predicates in List- 
ing 4—txt_pos and txt_posl. The 
clauses for these two predicates 
are: 
txt_pos :- 
makewindow(1,7,0,"Text Mode", 
0,0,25,80), 
write("\nPress left button to 
locate cursor position"), 
repeat, 
msm_stat(Button,Row,Col), 
txt_pos1(Button,Row,Col). 


txt_pos1(1,Row,Col):- 
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MSMOUSE FUNCTION # 8 */ 

msm_vert(Min,Max) :- 7* Cit) ¥/ 
bios($33, reg(8,0,Min,Max,0,0,0,0), 

MSMOUSE FUNCTION # 9 */ 

msm_block(Row, Col ,Mask):- LCi tied) oe 
bios($33,reg(9,Col ,Row,Mask,0,0,0,0), 

MSMOUSE FUNCTION # 10 */ 

msm_text (Select, Screen, Cursor):- J*® i,t, ty * 
bios($33, reg(10,Select,Screen,Cursor,0,0,0,0), 

MSMOUSE FUNCTION # 11 */ 

msm_mickey(Row,Col):- 
bios($33,reg(11,0,0,0,0,0,0,0), 


FegGe,) -CKeDN eee ee 
Col=CX, Row=DX. 


/* (0,0) */ 


MSMOUSE FUNCTION # 12 */ 

msm_user (Mask, Address): - /* Ci,i) */ 
bios($33,reg(12,0,Mask,Address,0,0,0,0), 

MSMOUSE FUNCTION # 13 */ 

msm_pen_on: - 


bios($33,reg(13,0,0,0,0,0,0,0), 


MSMOUSE FUNCTION # 14 */ 


msm_pen_off:- 
bios($33,reg(14,0,0,0,0,0,0,0), 


MSMOUSE FUNCTION # 15 */ 

msm_ratio(Vert,Horz):- LEGA es 
bios($33,reg(15,0,Horz,Vert,0,0,0,0), 

MSMOUSE FUNCTION # 16 */ 

msm_cond(UY , UX, LY,LX):- Udall CDs Pb ben et! 
bios($33,reg(16,0,UX,UY,LX,LY,0,0), 

MSMOUSE FUNCTION # 19 */ 


msm_ds(MPS):- 
bios($33,reg(19,0,0,MPS,0,0,0,0), 


HoPAG EL IF 


HREKKKKKKKKKKKKE End of MSM-DRV.PRO RERKEKEEEKEKKEEEEEEKKE */ 
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LISTING 3: BUTTONS.PRO 


/* HREKEKEKEERKEEREEREREREEREREREEREREREEEEREEREREEREREERRERE */ 


/* This is a testing program to report the pressed button. */ 
/* HHKKKKKEEKERERERREREREEREEEEKREREEREREREREEREREREREEEEKKE */ 


include "msm-drv.pro" 


PREDICATES 
button_status 
repeat 
button( INTEGER, STRING) 
Bmeaning( INTEGER, STRING) 


CLAUSES 
button_status :- 
msm_init, 
msm_show, 
repeat, 
msm_stat(X,_,_), 
button(X,_). 


repeat. 
repeat :- repeat. 


Table of Mouse Buttons combination for PC MOUSE (3 button mouse). 


For users of Microsoft Mouse only 0,1,2,3 combinations are 
applicable. 


Button Status is an integer referring to the pressed 
button combinations. The following combinations are 
recognized: 


initial status (no button is pressed) 
left ; 
left + right (6) 
right; (right) 
right + middle (6) 
left + right (left + right) 
middle; (middle) 
middle + left; (6) 
middle + right; (3) 
left + middle + right; .... (left + middle) 
middle + left (6) 
right + middle 
7 left + middle + right 


(right + middle) 
(left + middle + right) 


button(X,Y) :- 
X <> 0, /* When X=0 then no button is pressed */ 
Bmeaning(X,Y), 
write("\n",Y,"\n"). 


Bmeaning(1,"left button is pressed"). 
Bmeaning(2,"right button is pressed"). 
Bmeaning(4,"middle button is pressed"). 


/* HHKKKRKHEKEKEKEEREEKRE END OF BUTTONS.PRO HRKAKKREREREREEREREREERE 7 


LISTING 4: POSITION.PRO 


/* HHEKEKKKRERERKEEREKREKRERERERERREREEEREREEREREREREEEEREREEE 


This program shows a technique to return cursor postion 
in both text mode (row and column of cursor), and 
graphics mode (X and Y coordinates of cursor). 


HRRKEREKRKERERERERKEEKREEERERREREREEREREREREREREREREEERERER */ 
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CAT AND MOUSE 


continued from page 97 
NewRow = Row/8, 
NewCol = Col/8, 


cursor (NewRow,NewCol), 

write(NewRow,",",NewCol), 

fail. 
txt_pos1(2,_,_). 
After the repeat subgoal, we get 
the status of the mouse (Button, 
Row, and Col), which we pass to 
txt_posl. There are two txt_posl 
clauses, which are selected by 
pressing the appropriate button 
on the mouse. Pressing the left 
button instantiates Button to the 
value 1, which matches with the 
first txt_posl clause. Notice that 
the fail in this clause causes back- 
tracking (in txt_pos) back to 
repeat. This backtracking allows 
the program to mark many posi- 
tions on the screen, as long as you 
only press the left button. When 
you press the right button, the 
program transfers control to the 
second clause for the txt_pos] 
predicate, the subgoal 
txt_pos(2,_,_) succeeds, and 
control returns to report_pos. 


END OF A TAIL 


This brings us to the end of this 
Turbo Prolog cat-and-mouse 
game—at least for the moment. 
During the chase, we’ve explored 
a number of mouse programming 
techniques that are unique to 
Turbo Prolog. First, we’ve exam- 
ined how basic mouse functions 
are called with the bios predicate. 
Second, we’ve used backtracking 
instead of recursion to continu- 
ously poll the mouse for activity. 
Third, we’ve explored how to 
associate the mouse with specific 
actions in our program. 

The mouse can be used in 
Turbo Prolog applications in a 
number of ways. For instance, you 
can use the mouse to dynamically 
move Turbo Prolog windows on 
the screen by pointing to a win- 
dow and dragging it to a new posi- 
tion. This same technique can 
also be used to resize a Turbo 
Prolog window. 

Another possible Turbo Prolog 
mouse application is to select 
strings of text displayed on the 
screen, and then move or copy 
those strings to a new screen loca- 
tion. In graphics mode, the mouse 
can be used to point or to draw 


lines, rectangles, polygons, and 
so forth; and to indicate the 
direction for rotation, reflection, 
perspective, and other kinds of 
graphical transformations of 
those figures. 

In the second article of this two- 
part series, we'll chase our mouse 
into two Turbo Prolog applica- 
tions. The first application will use 
the mouse with a pop-up menu; in 
fact, we'll modify the Turbo Prolog 
Toolbox’s menu tools to work with 
the mouse. The second applica- 
tion will allow us to scroll text in a 
window by using horizontal and/ 
or vertical scroll bars similar to 
those on the Macintosh. Tune in 
next time as the Turbo Prolog 
mouse chase continues. 
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Listings may be downloaded from 
CompuServe as MOUSE1.ARC. 


include "msm-drv.pro" 


/* include mouse driver file */ 


PREDICATES 


report_pos 
txt_pos 

txt_pos1( INTEGER, INTEGER, INTEGER) 
gra_pos 

gra_pos1( INTEGER, INTEGER, INTEGER) 
repeat 


CLAUSES 


/* 
/* 
/* 


/* 


/* 


/* 


HHKKKKKKKKKKKEEEEKEKEEEEEREREREREREREEEREREREKKKK KKK KKK */ 


REPORT CURSOR POSITION BOTH IN TEXT, AND GRAPHIC MODE */ 


HHKKKKI KERIKERI RIKER RIKER IKE HERE EERE EERIE */ 


report_pos :- 
msm_init, 
msm_show, 
repeat, 
txt_pos, 
gra_pos. 


KREKKKEKKEKEKEKERKREREKREREEK xf 


TEXT MODE */. 


KRRKKKKHEREKREREKEKEKKKKKKEEE */ 


txt_pos :- 
makewindow(1,7,0,"Text Mode",0,0,25,80), 
write("\n Press left button to indicate cursor position"), 
repeat, 
msm_stat(Button,Row,Col), 
txt_pos1(Button,Row,Col). 


If Button = 1, you pressed left button to report position */ 
txt_pos1(1,Row,Col):- 
NewRow = Row/8, /* scale cursor row position to text mode */ 
NewCol = Col/8, /* scale cursor col position to text mode */ 
cursor(NewRow,NewCol), 
write(NewRow,",",NewCol), 
fail. 
If Button = 2, you pressed the right button to end text mode */ 


txt_pos1(2,_,_). 


HKKKKKKEKREKEKEREKREEREEEKE */ 


GRAPHIC MODE wf 


REKRKREREKREREREREEREEEEKEEK */ 


gra_pos :- 
graphics(2,1,4), 
write("\n Press left button to indicate cursor position"), 
msm_show, 
repeat, 
msm_stat(Button,X,Y), 
gra_pos1(Button,X,Y). 


gra_posi1(1,X,Y) :- /* left 
NewX = (X/200)*31999, /* scale X coord. to graphic mode */ 
NewY = (Y/640)*31999, /* scale Y coord. to graphic mode */ 
Xpos=X/8, Ypos=Y/8, cursor(Xpos,Ypos), 
write(NewX , "," , NewY), 
fail. 


button is pressed */ 


gra_posi(2,_,_). 


repeat. 
repeat :- repeat. 


KEKKKKEKEKEKEEKRERERKEKEK END OF POSITION. PRO ******#eeexe */ 
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TURBO BASIC 


VARIABLE VARIATIONS 


The area in which a variable is known can be as important 


as the data it contains. 


David A. Williams 


Modern BASIC compilers such as Turbo 

Basic not only enable your programs to 

run faster, but they also have many fea- 
(2 tures that make your programs easier to 

write, debug, and maintain. Examples 
a——s_ include procedures (subprograms), multi- 
line defined functions, block-structured program 
statements, and the “scoping” of variables. Of these 
extensions, variable scoping is by far the subtlest and 
most alien to the original spirit of Dartmouth BASIC. 
The scoping of Turbo Basic’s variables is well worth 
a close and thorough look. 


SQUARE ONE 


GLOBAL HEGEMONY 


Interpreted BASIC treats all variables as global. 
Once you declare a variable, it is available to be read 
or modified by any statement in the program. This 
makes each variable identifier absolutely unique. You 
can use a given variable name for only one entity in 
a single program, whether the variable is in the main 
program or in a small subroutine. 

This is no great hardship if you write small, simple 
programs; you can easily remember which variable 
names have been used. The larger the program, 
however, the more likely you are to make a mistake. 
Index variables, which act as counters in 
FOR..NEXT loops, are especially difficult to track. 
Consider the following program fragment: 
cLS 
DIB. us 
1=37.4 
X=23 


GOSUB CalcIt 


PRINT 1*X 


During development of this program, you decide to 
save some effort and “drop in” the small section of 
code shown below that you've lifted from another 
program: 
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Calclt: 
FOR I=1 TO 10 
FOR J=1 TO 20 
ACI)=ACI)*BCJ) 
NEXT J 
NEXT I 
RETURN 


Note that the variable I appears in both sections of 
code, even though there is no logical connection 
between the two sections. The I in subroutine Calclt 
is used only as a FOR..NEXT loop counter and 
bears no relation to variable I in the main program. 
The two sections do not conflict with one another 
from a syntactic standpoint, but they may logically 
interfere with one another unless you take specific 
steps to ensure that they don’t. 

This limitation makes it very difficult to write 
generic routines that you can combine into a single 
library file and use in many different programs. A 
library of such commonly used routines can save you 
many hours of programming and debugging time 
and let you concentrate on creating your main pro- 
gram. Libraries are most comprehensible if you 
establish a system in which a particular variable 
name always represents the same kind of quantity, or 
is always used for the same purpose in every routine. 
Using the variable I only within FOR..NEXT loops 
would be a good example of this sort of convention. 
Before you can follow this system, however, you 
need a way to keep the multiple instances of identi- 
fier I in all of your various library routines from con- 
flicting with one another. 

Language designers created the concept of scope 
to meet this need. The language compiler restricts 
the use of local variables to a certain area of the pro- 
gram. This area, called the local variable’s scope, is 
the region of the program in which the variable is 
“known” (i.e., where the variable is available to be 
read from or written to). 

The compiler builds a conceptual fence that iso- 
lates one section of the program from another. Since 
program code on one side of the fence is indepen- 
dent from that on the other, you can have identical 
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Bradley Ream 
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VARIABLE 
continued from page 100 


variable names for different vari- 
ables, as long as each instance of 
a name resides within its own 
fenced-off backyard. Turbo Basic 
constructs these fences around 
routines written as procedures 
and as defined functions, and also 
around chained programs. On the 
other hand, program code 
imported with the $INCLUDE 
metastatement, and subroutines 
called via GOSUB, share the 
scope of the main program and 
do not have a separate scope. 


THE VARIABLE BESTIARY 


While the term “local” is often 
applied to any variable whose 
access is limited in some way, the 
true definition of local variable 
under Turbo Basic is more pre- 
cise. A running program, upon 
entering a procedure or function, 
establishes local variables on the 
stack. These local variables disap- 
pear and their values are lost dur- 
ing stack clean-up when the pro- 
gram exits the procedure or 
function. 

A static variable is similar to a 
local variable in that its scope is 
limited to the routine in which it 
is declared. However, the com- 
piler assigns each static variable a 
permanent location in memory, so 
the static variable retains its exis- 
tence and its value even after the 
program exits the routine that 
owns the variable. 

Of course, you usually don’t 
want to completely isolate subpro- 
grams from your main program. 
You have to pass variables and 
values to the routine and send the 
results back to the main program. 
One way of doing this is with an 
argument list, a list of variables or 
values passed to the procedure or 
function. Variables in the argu- 
ment list are available to both the 
caller and the routine being 
called. There are limits to the use 
of argument lists, most notably 
that array variables cannot be 
passed to functions as arguments. 
Arrays may, however, be passed as 
arguments to procedures. 

Shared variables are available to 
both the subprogram in which 
they are declared and to the main 
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program, but not to other sub- 
programs. They can be used to 
augment the argument list of a 
subprogram, because variables of 
any type can be shared variables. 
Arrays declared in a function 
should be declared as SHARED 
with the main program, because 
(as mentioned above) array vari- 
ables cannot be passed to func- 
tions through argument lists. 

With earlier BASICs, the term 
global variable is sometimes used 
interchangeably with shared vari- 
able, but a global variable is avail- 
able to all parts of a program with- 
out restriction. Any program 
statement in the main program, in 
any procedure, or in a function 
can access a global variable. 
Turbo Basic, however, does not 
support global variables in this 
sense. By default the scope of a 
variable in Turbo Basic is limited 
to the entity in which it is defined 
(either the main program or a 
subprogram), and no single state- 
ment declares a variable to be 
global. To make a Turbo Basic 
variable effectively global, you 
must declare it as SHARED within 
every subprogram in the program. 

In certain situations, a variable’s 
status defaults to local, static, or 
shared. But you can also declare 
the status of a variable with the 
LOCAL, STATIC, and SHARED 
statements. You can only use these 
statements within procedures and 
functions, and they must appear 
before the code body of the pro- 
cedure or function. 


PROCEDURES AND THEIR 
VARIABLES 


A procedure is a multiline program 
segment bounded by the SUB and 
END SUB statements. The main 
program calls a procedure with a 
CALL statement, which may have 
an argument list. Although the 
Turbo Basic Owner’s Handbook 
states otherwise on page 355, vari- 
ables declared within a procedure 
are static by default, but you may 
also declare variables to be local 
or shared. You cannot declare any 
variable in a LOCAL, STATIC, or 
SHARED statement if that same 
variable also appears in the argu- 
ment list. 


Consider the following ex- 
ample: 
cLS 
A=3 
B=56 
x=5 
Y=2 
C=6 
CALL TEST(X,Y) 
PRINT C,X,A,Y 
END 
SUB TEST(A,D) 
LOCAL B 
SHARED C 
B=A°2 
C=C+A 
D=4*B 
E=E+1 
END SUB 
The PRINT statement displays: 
1m 5: 3 100 


The variable B in the procedure 
is declared as local; it is main- 
tained on the stack and its value 
will be lost when the program 
exits the procedure. The variable 
B in the procedure is different 
from the variable B in the main 
program, because their scopes do 
not intersect. 

The main purpose of the 
SHARED statement in procedure 
TEST is to make the main pro- 
gram variable C available to TEST 
without having to put C in the 
argument list. Shared variable C 
starts out with the value 6 assigned 
in the main program. C is then 
changed by the procedure TEST; 
when printed, C has the new 
value of 11. 

X is not changed by procedure 
TEST, but Y assumes the value of 
D. This example illustrates how a 
value may be returned to the main 
program through the argument 
list. The main program’s variable 
A does not change, since it is 
independent of the variable A in 
the procedure’s argument list. 

You must keep default condi- 
tions in mind, but it is not neces- 
sarily a good idea to depend on 
them. Being explicit about vari- 
able scoping costs nothing in code 
speed and costs very little in com- 
pilation time. E, which by default 
is static, is initialized to 0 when 
the program begins execution, 
and is incremented by | each time 
the procedure TEST executes. 
The incremented value remains 
in memory between executions of 
TEST. There is no reason to 
declare B as local, as opposed to 
letting it be static by default (like 


variable E). Good practice, how- 
ever, suggests that you declare the 
procedure’s own variables with 
the STATIC or LOCAL statements 
as desired so that anyone looking 
at your program listing (including 
you) can see the nature of your 
variables at a glance. Further- 
more, Borland does not guarantee 
that default conditions will not 
change in future releases of the 
compiler. To this end, we should 
add the statement STATIC E to 
the example program. 


SHARING STRATEGIES 


For any given variable, you have 
to choose between using the argu- 
ment list or the SHARED state- 
ment when you are designing a 
procedure. If your procedure is 
for use within a single program, 
the SHARED statement is very 
convenient. On the other hand, if 
you are designing a routine for 
incorporation into a library that is 
used by many programs, it is bet- 
ter to pass everything possible 
through argument lists. You will 
be able to use the routine in any 
program without worrying about 
matching shared variable names. 

You can pass arrays either 
through the argument list, or by 
declaring them as SHARED 
within the procedure. With the 
former method, use the format 
arrayname(n), where n is the 
number of dimensions. Keep in 
mind that passing arrays in this 
way applies only to procedures; 
arrays cannot be passed to func- 
tions as arguments. In the 
SHARED statement, use 
arrayname(). 

An additional advantage of 
using argument lists in passing 
values to procedures is that the 
actual parameters passed as argu- 
ments can be different variables 
on each invocation, whereas a 
shared variable is always the same 
variable on every invocation. For 
example, consider the following 
procedure header: 


SUB AVERAGE (NumArray(1),Average) 


Here, the formal parameter 
NuméArray(1) specifies that a one- 
dimensional array may be passed 
to AVERAGE. It doesn’t say which 
array. In other words, if you have 
two arrays, Arrayl and Array2, 
either one may be passed to 
AVERAGE in the NumArray(1) 
formal parameter. 


On the other hand, if you don’t 
include an array formal parameter 
in the argument list, and instead 
declare Arrayl as SHARED within 
procedure AVERAGE, the actual 
array variable Array] is the only 
array that will be available to 
AVERAGE. 


DEFINED FUNCTIONS 


Support of multiline defined func- 
tions is one of Turbo Basic’s more 
significant enhancements. Older 
BASIC interpreters limit defined 
functions to a single line. Using 
multiple lines in Turbo Basic 
allows the creation of consider- 
ably more complex functions. 

While similar to procedures, 
defined functions have several 
distinctive properties. You exe- 
cute a function by placing its 
name in an expression, as in 
A=FNTEST(X,Y). The function 
name takes on a value during the 
function’s execution, and this 
value is returned to the caller as 
though the name of the function 
were the name of a variable. 

A function is not required to 
return a value in the function 
name; it may simply perform its 
work by executing some state- 
ments. Values may also be passed 
back to the caller through shared 
variables. Note that, unlike pro- 
cedures, functions cannot pass 
values back to the main program 
through the argument list. An- 
other difference between func- 
tions and procedures is that vari- 
ables appearing in a function’s 
argument list are local to that 
function, but other variables in 
the function are by default shared 
with the main program unless 
declared otherwise. 

The following example illus- 
trates some of the properties of 
variables in defined functions: 
cLS 
X=5 
Y=3 
A=17 
ANSWER=FNTEST(X,Y) 

PRINT ANSWER,C,A 
END 
DEF FNTEST(A,B) 

FNTEST=A°2+2*A*B+B 2 

C=A+B 
END DEF 
The PRINT statement displays the 
output: 


64 8 17 
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THE WINDOW BOX 
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WINDOW BOX (n): 

1. A flower box that enhances the beauty of 
a window. 

2. A windowing toolbox for C programmers. 


Enhance the beauty of your C applications 
with THE WINDOW BOX. 


ADD SOME PIZAZZ! 


THE WINDOW BOX lets you ELECTRIFY 
your programs with pop-up windows, pull- 
down menus with highlight bar selection, and 
context sensitive help. Watch your screen go 
blank when your program is idle. Assign 
functions to the function keys. Much more! 


ADD SOME POWER! 


Read many fields with one operation. Data 
entry windows offer many formats, com- 
plete cursor navigation, and let you tie veri- 
fication functions to any field. Use scrolling 
and text-editing windows, too. Print a 
window, not necessarily the whole screen. 
(Super for mailing labels!) Much more! 


SOURCE CODE PROVIDED. 


Contains no assembler code! Only standard 
C code. See how things work. Understand 
how things work. Change how things work. 
Compatible with all major C compilers. 
Requires MS-DOS/PC-DOS. 


REASONABLE PRICE. 

And no royalties. Only $49.50 including 
shipping and tax. Or, try the demo disk and 
inspect the manual for only $10. Like what 
you see, and apply this $10 to the purchase 
price. Overseas add $5.00 per order and we 
will Air Mail. 


SATISFACTION GUARANTEED, or return in 
30 days for a full refund. 
Mastercard/Visa: Call 412-487-4282. 
Or, send checks (U.S. funds) to: 
Vertical Horizons Software 
113 Lingay Drive 
Glemshaw, PA 15116 
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A function is given a value by 
assigning the value of some 
expression to the function name, 
as in the statement: 


FNTEST=A2+2*A*B+B 2 


The main program can access this 
value by using the function name 
in an expression. The expression 
does not have to be an assign- 
ment statement. I could also have 
written: 


PRINT FNTEST(X,Y) 

Note that variable C, which is a 
shared variable by default, is avail- 
able to the main program even 
though it was never declared 
there. Shared variables are the 
best way to operate on arrays, 
since you can’t pass complete 
arrays to functions through the 
argument list. Only the individual 
elements of an array can be 
passed in this way. 

A and B are local by virtue of 
appearing in the argument list. If 
your function requires the use of 
temporary variables, you can de- 
clare them with the LOCAL or 
STATIC statements to avoid inter- 
ference with main program vari- 
ables. Again, good practice dic- 
tates that you declare all of your 
variables as having a specific 
scope, rather than rely upon 
default conditions. This means 
that we should add the statement 
SHARED C to the FNTEST 
function. 

Defined functions have another 
property not shared by proce- 
dures, as shown below: 

CL> 

X=1 

Y=2 

z=3 
DUMMY=FNTEST(X,Y,2Z) 
PRINT X 

CALL TEST(X,Y,2Z) 
PRINT X 

END 

DEF FNTEST(A,B,C) 

=A+B*C 
END DEF 
SUB TEST(A,B,C) 

A=A+B*C 
END SUB 
The function and the procedure 
seem identical, yet the first PRINT 
X statement will display 1, where- 
as the second will display 7. In the 
first case, the function’s argument 
list passes only the value of the 
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variable X. The function cannot 
change X since it doesn’t know 
where X is stored. This is called 
passing by value. In the second 
case, the procedure’s argument list 
passes the address of the variable 
X. The procedure reads the origi- 
nal value, performs the operation, 
then returns the result to the vari- 
able X. This is called passing by ref- 
erence. If you change the CALL 
statement to CALL TEST((X),Y,Z), 
the value of X will not change 
because this tells the compiler to 
pass only the value of X. 


SINGLE-LINE FUNCTIONS 


Single-line functions have proper- 
ties similar to multiline functions 
that don’t use the LOCAL, 
STATIC, or SHARED statements. 
Variables in the argument list are 
local, and all variables within the 
function’s definition are shared 
with the caller. The following 
example illustrates a simple 
single-line function: 

CLS 

B=10 

X=2 

PRINT FNTEST(X) 

END 

DEF FNTESTC(Y)=B+tY 


The PRINT statement displays 12. 


CHAINED PROGRAMS 


Chained programs are relics of the 
days of small memory systems and 
the limited power of BASIC inter- 
preters. Programs of a reasonable 
size often could not fit completely 
in memory, so they were divided 
into multiple modules that passed 
control from one to another, with 
each module taking its turn in 
memory while it executed. Turbo 
Basic’s ability to use all available 
memory will probably allow you to 
combine previously chained pro- 
grams into a single module. Turbo 
Basic does support chaining to a 
limited extent, and the subject of 
local variables is not complete 
without mentioning chaining. 
With the statement CHAIN 
<filespec>, a program can pass 
execution to a second program 
that has been compiled with the 


-EXE or . TBC extension. The 
second program can pass execu- 
tion back either to the first pro- 
gram, to a third program, or to 
DOS. The scope of all variables in 
a series of chained programs is 
limited to the single program that 
contains those variables. In other 
words, if PROGA chains to 
PROGB, PROGB has no knowl- 
edge of, or access to, variables 
within PROGA. 

The COMMON statement 
allows you to share variables 
among programs in a chained 
series of programs. COMMON, 
accompanied by a variable list, 
must appear in both the called 
and the calling programs. The 
variable list in each program must 
contain the same number and 
type of variables, listed in the 
same order. To share variables A, 
B, MyArray, and BUF$, the fol- 
lowing statement must appear in 
all programs that will share these 
variables, in exactly this form: 


COMMON A, B, MyArray(1), BUFS 


The scope of all variables cited in 
the COMMON statement is thus 
expanded to include all programs 
that contain the COMMON state- 
ment. Again, it is crucial that each 
variable in all COMMON state- 
ments has the same name, the 
same type, and is in the same 
order in all instances of the 
COMMON statement, or else 

a runtime error will occur. 


VARIABLE STARS 


As author Tom Swan has said, 
statements are what a program 
does, and variables are what a pro- 
gram knows. When first learning a 
programming language, users 
often look at the statements that 
make up a program without think- 
ing very much about the variables 
that are acted upon by those state- 
ments. Taking the time to under- 
stand how scoping affects Turbo 
Basic’s variables will make it much 
easier to create programs that 
work correctly and read well, both 
now and six months from now. @ 


David A. Williams is a principal staff 
engineer for a major aerospace com- 
pany. He can be reached at 2452 
Chase Circle, Clearwater, Florida 
34624. 


INSTANTANEOUS 


HELP SCREENS 


Tuck some helpful information in the screens 


hiding behind your screen. 


Ralph Roberts 


Instantaneous help screens are an easy 
way to add professional “slickness” to 
your Turbo Basic software. These screens 
appear instantly at the touch of a key, 
then neatly disappear until called again. 

You can have up to eight display 
“pages” in text mode, but only on CGA, EGA, or 
VGA adapters. The page being processed and/or 
displayed is set using the SCREEN statement. The 
general format is: 


SCREEN [mode] [,[colorflag] [,[apage] [, [vpage]. 


The mode must be 0 (i.e., the text default), and 
colorflag is not used (though you can use the 
COLOR statement as much as desired). The trick is 
the last two parameters, apage and vpage. apage, an 
integer value from 0 to 7, controls which text page is 
written to. vpage selects the one shown. 

In a help screen application, you want to devise a 
routine to load help screens during program initiali- 
zation so that the screens do not appear until they’re 
called. Use event trapping to make a screen pop into 
place when a specific “help” key is pressed. You write 
to one screen while showing another. 

At the start of the program, F1 is defined as invok- 
ing the HELP subroutine; the F10 EndIt subroutine 
provides an exit from the program. When a subrou- 
tine is assigned to a function key, you must turn the 
key on. Turbo Basic then checks between each state- 
ment to see if that key has been pressed. If it has, the 
associated operation is performed. 

Note that this will not work on the IBM Mono- 
chrome Display Adapter, which contains only 4K of 
text buffer; this is enough for a single page and no 
more. @ 


PROGRAMMER 


Ralph Roberts is a freelance writer and ham radio operator 
(WA4NUO) who has written books on many topics, in- 
cluding Turbo Basic, Turbo Prolog, Reflex, and auto- 
graph collecting. 


Listings may be downloaded from CompuServe as 
HLPSCR.ARC. 
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LISTING 1: SCREEN.BAS 


Instantaneous Help Screens by Ralph Roberts 


CLS : ON KEY (1) GOSUB ONE : ON KEY (2) GOSUB TWO 
ON KEY (10) GOSUB EndIt : KEY (1) ON : KEY (2) ON : KEY (10) ON 
SCREEN ,,1,0 ' Write to Screen 1 but show Screen 0! 


COLOR 14 ' Make it a different color 
FOR X% = 117042 ' Use integers for loops, it's faster 
PRINT “This is an instantaneous HELP Screen. "; 
NEXT X% =: PRINT ' This loop invisibly fills the HELP screen 
PRINT : PRINT * (press any key to return to program)" 
COLOR 15 ' color for second HELP screen 


SCREEN ,,2,0 
FOR X% = 17042 ' Use integers for loops, it's faster. 

PRINT “This is yet another HELP Screen. "; 
NEXT X% : PRINT ' This loop invisibly fills the 2nd HELP screen 
PRINT : PRINT ™ (press any key to return to program)" 
COLOR 7 " Restore color to default 
SCREEN ,,0 ' Restore screen writing to Screen 0 


MainProgram: 
LOCATE 1,20 : PRINT "Instantaneous Screens" 
LOCATE 25,20 : PRINT “Hit F1 for Help, F2 or Help2, or F10 to end"; 
LOCATE 12,30 : COLOR 0,7 : PRINT DATES,TIMES; : COLOR 7,0 
GOTO MainProgram 


EndIt: 

CLS : COLOR 7,0 : END 
ONE: 

HelpScreen = 1 : GOTO HELP 
WO: 


HelpScreen = 2 : GOTO HELP 
HELP: 
SCREEN ,,HelpScreen 
Wai tABit: 
AS = INKEYS : IF AS = "" THEN WaitABit 
SCREEN ,,0 ‘ restore main program screen & continue operation 
RETURN 


' POP up the called for screen 


TURBO BASIC 


TURBO BASIC 


PICK A FILE, ANY FILE 


File selection menus let your user “peruse and choose,” with 
a little help from the Turbo Basic Database Toolbox. 


Marty Franz 


Sooner or later, your programs will need 
to get a filename from your user. When 
that time arrives, you could execute an 
INPUT statement asking your user to type 
the drive, directory, and filename. In this 
situation, the task of specifying a legal 
filename (eight letters, digits, and common symbols; 
followed by a period; optionally followed by one to 
three characters) falls completely upon your user— 
and leaves plenty of room for a naive user to make a 
mistake. 

Isn’t there a better way to ensure that you get a 
correct filename from your user? Wouldn’t it be nicer 
if your user could highlight a file in a list that you 
display on the screen, and then select that file by 
pressing Enter? 

You can make this scenario a reality by rounding 
out your Turbo Basic programs with the routines 
demonstrated in the file selection program 
PICKER.BAS (Listing 1). PICKER prompts the user 
for a drive and directory, and then displays a list of 
the files in that directory. The selected file is high- 
lighted by using the up and down arrow keys, and 
the Home and End keys. If Enter is pressed, the 
highlighted file is displayed for confirmation; if Esc 
is pressed, entry is aborted. 

Although PICKER is a simple program, it illus- 
trates the use of the various Turbo Basic routines 
described below. These routines, which can be 
modified and incorporated into your own programs, 
provide good examples of the use of Turbo Basic’s 
powerful CALL INTERRUPT statement. They also 
demonstrate the use of subroutines from the Turbo 
Basic Database Toolbox for handling the details of 
getting input from the user, scrolling, and writing to 
the screen. 


INTERRUPT HINTS 

Before we examine the implementation of Turbo 
Basic’s CALL INTERRUPT statement in PICKER, 
let’s look for a moment at the way that Turbo Basic 
handles interrupts. 


PROGRAMMER 


Using interrupts from interpreted BASICA is 
tedious and requires an assembler. You have to write 
assembly language routines to pass control and 
parameters from your BASIC program to the inter- 
rupt routine, then generate the interrupt, and finally 
clean up the stack and come back. Turbo Basic, how- 
ever, contains a CALL INTERRUPT statement that 
allows you to generate any valid 8088 interrupt by 
specifying the interrupt number. For example, to call 
DOS using the CALL INTERRUPT statement, you 
code: 

CALL INTERRUPT &H21 


Turbo Basic provides a REG buffer to hold 8088 
register values before and after an interrupt call. The 
Turbo Basic Owner’s Handbook tells exactly which sub- 
scripted element in the REG buffer stands for which 
register in the buffer. For example, element 0 holds 
the flags register, element | holds the AX register, 
and so on. Rather than attempting to remember all 
these correlations, you should always include the file 
REGNAMES.INC from the Turbo Basic distribution 
disk, and define named constants for the frequently 
used register values. Your code will be much more 
readable if you refer to registers and DOS function 
call services by their symbolic names: 

&F indF irst=&H4E00 

REG %AX, XFindFirst 

This is much easier to read than the literal 
equivalent: 


REG 1,8H4E00 


Following readability conventions makes future 
maintenance of your program much easier. 

To make effective use of CALL INTERRUPT, you 
should have both a DOS technical reference manual 
and a good reference to PC BIOS routines. Other 
books on IBM PC assembly language are also 
helpful. 


LOOKING FOR FILES 

The routines MsDos and FNDosError set the regis- 
ters and check for errors; we can also call them to 
perform directory searching chores. Searching 
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a DOS directory involves two calls: 
Find First Matching File and Find 
Next Matching File. The logic for 
using these calls (assuming that 
you already have a file mask) can 


LISTING 1: PICKER.BAS 


PICKER.BAS: Demonstration file picker program 


: ; version: 2-10-88 
be expressed in pseudo-code: compiler: Turbo BASIC 1.0 
Find first file matching the mask uses: REGNAMES.INC, ENTSUBS.BOX, SCRNASM.BOX, SCRNSUBS.BOX 


' 
' 
1 
' 
' 
lf there was a file found then ‘ module type: .EXE 
Do ' 

Find the next file ' (C) Copyright 1987 Marty Franz 

that matches the mask; : 

Loop until no more files : 

1 

' 


End If 
The first of PICKER’s two main 
parts contains two versions of this DEFINT A-Z 


logic. The version in the subrou- 
tine FNCountFiles returns a count | | $!NCLUDE "REGNAMES. INC" 


This program prompts the user for a list of files and displays 
them, allowing selection using the up and down arrow keys, 
Home, End, and Esc. 


. SINCLUDE "ENTSUBS.BOX" ‘From the Turbo BASIC Database Toolbox 
of the files matching the mask SINCLUDE "SCRNASM.BOX" 
and enables you to dynamically $SINCLUDE "SCRNSUBS.BOX" 
allocate an array to hold the 
filenames. Another version of aFalse=0 
this logic is in the subroutine BIT Deora se) 
FNGetFiles, which fills a string %GetDTA=&H2F00 ‘Dos and Bios calls 
array with all the files that match %F indFirst=&H4E00 
the mask. The following Turbo %F indNext=&H4F00 
Basic code statements let you use 
these roses: y “SearchAttribute=&H21 ‘file attribute: R/O + archive 
r %F i LeNameOf fs=30 ‘filename offset within DTA 

Mask$="* ,*" 
Number F i les=FNCountF i les(Mask$) Z*NoError=0 ‘Dos error code 
DIM FileNames$(Number Files) 
CALL GetFiles(Mask$, Fi leNames$()) SUB EntUserHook(Ch$) 

- F ' This routine is required by the Turbo BASIC Database Toolbox entry 

If a nonexistent or illegal mask ' functions. 

is entered, the routines find no Ch$=INKEYS 


files. In this case, calling the func- END SUB 
tion FNDosError returns the 

h Biles. d DEF FNLO(X) 
reason Ww y no es are oun _ ' Return the low byte of integer X. 
While officially the code 2 signi- FNLO=X MOD 256 
fies No Files Found, and the code END DEF 
18 indicates No More Files, any TER Fae 

ee : i 

hades one Sek ae ee ' Return the high byte of integer xX. 
treated in the same way. Let’s FNHi=INT(X/256) 
amend the logic given above to be | | END DEF 
the following: 
Mask$="**" 


Number F i Lles=FNCountFi les(Mask$) 
IF NumberFiles>O THEN 


SUB StringAddr(Segment , Of fset ,S$) 
' Subroutine to get the segment and offset of a string. Gets 
' the segment from the first two bytes of the default segment. 
' Gets the offset by reading the string descriptor and getting 


DIM Fi leNames$(Number Fi Les) ' the third and fourth bytes of that. 

CALL GetFiles(Mask$, FileNames$()) LOCAL 0 
ELSE 

Segment=PEEK(0)+256*PEEK(1 

PRINT "No files found." nee ) ol? 
END IF DEF SEG = VARSEG(S$) 
As shown here, the first part of Of fset=PEEK(0+2)+256*PEEK(0+3) 
PICKER handles the actual direc- a 
tory search; we'll jump farther into 
PICKER shortly. First, however, DEF FNASCIIZ$(Segment , Offset ,MaxLen) 

ou need to know about three ' Get an ASCIIZ string from memory at the location given by 
y : 
important wrinkles with respect ' Segment:Offset. MaxLen is a check on the length of the 


' string to get. 
ei: LOCAL P,N,S$ 
Attribute Mask. Searching directo- sg="" 


ries requires you to specify an N=0 
attribute mask, along with the file- BoE oe F 
name. The attribute mask tells DOS ven See Pee 
which types of directory entries 
you are seeking. The exact bit 
meanings (when bits are equal to 
one) are given below: 

continued on page 108 


to directory searches in BASIC. 
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WHILE PEEK(P) AND N<=MaxLen 
S$=S$+CHRS(PEEK(P)) 
INCR P 
INCR N 

WEND 

DEF SEG 

FNASCIIZ$=S$ 

END DEF 


DEF FNDosError 
' Return the last DOS error code received. 
IF (REG(O) AND &HO1) THEN 
FNDosError=REG(%AX) 
ELSE 
FNDosError=0 
END IF 
END DEF 


SUB MsDos(N) 
' Perform MS DOS call N. Assumes the other registers have been 
' set up already. N is used as AX value. 
REG 1,N 
CALL INTERRUPT &H21 
END SUB 


SUB GetDosDTA(Segment , Offset) 
' Get the current Dos DTA segment and offset. If both are zero 
' then an error occurred. 
Of fset=0:Segment=0 
CALL MsDos(%GetDTA) 
IF FNDosError=NoError THEN 
Of fset=REG(%BX) 
Segment=REG(%ES) 
END IF 
END SUB 


DEF FNCountFiles(FileSpec$) 
' 


Return a count of the files matching the filespec. Use this 
subroutine to pre-allocate arrays for sorting and choosing. 
If it returns 0 then no files were found; this means checking 
FNDosError for the reason. 
LOCAL Segment, Offset ,Mask$ 
Mask$=F ij leSpec$+CHR$(0) 
CALL StringAddr(Segment , Offset ,Mask$) 
REG %CX,%*SearchAttribute 
REG *DX,Offset 
REG %DS, Segment 
CALL MsDos(%FindFirst) 
IF FNDosError=%NoError THEN 
Count=0 
DO 
Count=Count+1 
CALL MsDos(%F indNext) 
LOOP UNTIL FNDosError 
FNCountF i les=Count 
ELSE 
FNCountF i les=0 
END IF 
END DEF 


SUB GetFiles(FileSpec$, FileArray$(1)) 
' Fill a string array with the files that match the filespec 
' passed. Fills up to upper bound of FileArray from lower 
' bound. 
LOCAL I,Segment,Offset,Mask$,DTASeg,DTAOffs 
CALL GetDosDTA(DTASeg,DTAOf fs) 
Mask$=F i leSpec$+CHR$(0) 
CALL StringAddr(Segment , Offset ,Mask$) 
REG %CX,%SearchAttribute 
REG %DX,O0ffset 
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PICK A FILE 
continued from page 107 


&HOI: file is read-only 
&H02: hidden file 
&H04: system file 
&H08: volume label 
&H10: subdirectory 
&H20: archive bit 


The archive bit is set whenever 
the file is written to and closed. 
It’s used by the DOS BACKUP 
utility to tell if the file has been 
changed since the last time it was 
written to. After the backup has 
been made, this bit is reset to 
zero. 

You can combine these bits into 
a single binary byte to tell DOS 
exactly what kinds of files you 
want to look for. PICKER uses the 
value &H21 to include read-only 
and nonarchive files in the 
search, and to omit everything 
else. You may also include hidden 
files, system files, and subdirecto- 
ries in the search. 


Disk Transfer Address. File infor- 
mation is placed in a Disk Transfer 
Address, or DTA, which is an area 
that DOS uses to pass information 
about directory entries. The layout 
of the DTA when you search direc- 
tories is summarized in Table 1. 


21 bytes - reserved by DOS 

1 byte - attribute found 

2 bytes - file’s time 

2 bytes - file’s date 

2 bytes - low word of file’s size 

2 bytes — high word of file’s size 

13 bytes - name and extension of file 


Table 1. The structure of the DOS 
Disk Transfer Area. 


The file’s name and extension 
are stored as a proper filename 
ending with a zero byte. (This type 
of filename is called an ASCIIZ 
string in the DOS documentation.) 
The function FNASCIIZ retrieves 
this filename from the DTA, and 
the subroutine GetDosDTA finds 
the segment and offset of DOS’s 
current DTA. DOS assumes that 
you already know which drive and 
path to search, and only gives you 
the specific filename and file- 
related information (date, time, 
and size). 


File specification mask. You need 
to pass an ASCIIZ string to DOS 
containing the actual file specifi- 
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“Behind the beauty of the 
Turbo C environment 
stands the brawn of 
a full-fledged compiler” 


Marty Franz, PC Tech Journal 


66 Taking compilers and pro- 
gram development tools into the 
next generation is Borland 
International's Turbo C, a 
$99.95 package that will stun 
you with in-RAM compilations 
that operate at warp speed. 


... a 21st century compiler at a 
preinflation 1967 price. Is it any 
wonder that Turbo C was 
included in the Best of 1987? 
Richard Hale Shaw, PC Magazine 


Turbo C represents an all-new 
price-performance level—one 
that will be hard to match, much 
less beat. 

Stephen Randy Davis, PC Magazine 


Turbo C showed excellent 
compiler speeds, good overall 
benchmark scores, and extraor- 
dinary floating-point performance. 
Scott Robert Ladd, Micro Cornucopia 99 


Our new Turbo C 1.5 is a 
technological tour de force 


At Borland we believe the slow 
way is no way, so Turbo C® is a 
racer. And as well as white-knuckle 
speed, Turbo C also gives you 
spectacular graphics. 


Minimum system requirements: For the \BM PS. 

sonal computers and all 100% compatibles. PC-DO: 

“Artwork metatile courtesy of Genigraphics® Corpor 

**Customer satisfaction is our main c 
0 


2™ and the IBM® tamily of per 
IS-DOS*) 2.0 or later. 384K 
‘Orpo 


Actual photograph of Turbo C graphics displayed on IBM 8514 screen.* 


Some of the reasons why the 

critics are so enthusiastic 

about Turbo C 1.5 

Turbo C now includes: 

¢ A professional-quality graphics 

library of over 70 functions 

A librarian that allows you to 

build your own object module 

libraries 

Context-sensitive help for the 

language and the library routines 

Text/video functions, 

including windows 

¢ 43- and 50-line mode support 

¢ VGA, CGA, EGA, Hercules, and 
IBM 8514 support 

¢ File search utility (GREP) 

¢ Sample graphics applications 

¢ More than 100 new functions 


The professional optimizing 
compiler for less than $100.00 


For professional-quality C at a 
sane price, nothing comes close to 
Turbo C. It’s super-fast and super- 
graphic. (We used it ourselves to 
write Eureka:” The Solver and to 
develop the presentation-quality 
graphics in Quattro,” our new and 
highly successful professional 
spreadsheet.) No one can deliver 
technical superiority like Borland. 


60-Day Money-back Guarantee ** 
For the dealer nearest you, 


Call (800) 543-7543 


REG 4DS, Segment 
CALL MsDos(%F indFirst) 
IF FNDosError=%NoError THEN 
I=1 
DO 
Fi LeArray$(I )=FNASCII1Z$(DTASeg,DTAOf fs+%F i leNameOf fs, 12) 
INCR I 
Call MsDos(%F indNext) 
LOOP UNTIL FNDosError OR I>UBOUND(FileArray$(1)) 
END IF 
END SUB 


SUB Choose(Pick,Visible,N,Choices$(1)) 
' Subroutine to choose an item from a string array. Pick holds 
' the item number the user chose. Visible is the number of 
' items on the screen... it can be less than N, the number of 
' jtems in the array. If so, the routine will scroll the list 
' up and down. The array Choices$ contains the items. When 
' complete, the variable EscPressed will be %True if the user 
' aborted, %False otherwise. Keys handled are Enter, Esc, the 
' up and down arrows, Home, and End. 
SHARED EscPressed 


SHARED Ent.NotAvailable,Ent.Escape,Ent.CR,Ent.UpLine,Ent.DnLine,_ 


Ent.Home, Ent.End 
LOCAL From,1I,R,Top,Bottom, Margin, Cmd 
Top=CSRLIN:Margin=POS(0) 
Bottom=ToptVisible-1 
Pick=1 
From=1 
GOSUB DisplayChoices 
Done=%False 
DO 
GOSUB Highlight 
DO 
CALL GetKeyStroke(Cmd) 
LOOP UNTIL Cmd<>Ent.NotAvai lable 
GOSUB LowLight 
SELECT CASE Cmd 
CASE Ent.Escape 
Done=4%T rue 
EscPressed=%T rue 
CASE Ent.CR 
Done=4T rue 
EscPressed=%False 
CASE Ent.UpLine 
IF Pick>1 THEN 
DECR Pick 
IF R>Top THEN 
DECR R 
ELSE 
CALL Scroll(1, Top, Bottom, Margin, 80, &HO7) 
LOCATE R,Margin 
PRINT Choices$(Pick); 
END IF 
ELSE 
CALL MinorErrorSound 
END IF 
CASE Ent.DnLine 
IF Pick<N THEN 
INCR Pick 
IF R<Bottom THEN 
INCR R 
ELSE 
CALL Scroll(0,Top,Bottom,Margin,80,&HO7) 
LOCATE R,Margin 
PRINT Choices$(Pick); 
END IF 
ELSE 
CALL MinorErrorSound 
END IF 
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PICK A FILE 
continued from page 108 


cation mask to search for. The 
string is passed to DOS by loading 
the DX register with the string’s 
offset, and loading the DS register 
with the string’s segment. You 
can’t just use Turbo Basic’s 
VARSEG and VARPTR functions 
to set these registers, because 
VARSEG and VARPTR return the 
segment and offset of the string’s 
descriptor, rather than of the 
string itself. To find the actual seg- 
ment and offset of the string’s 
data, you need to obtain the string 
data segment from the first two 
bytes of Turbo Basic’s default 

data segment. The subroutine 
StringAddr, which uses the third 
and fourth bytes of the string’s 
descriptor, finds the offset of the 
string data within this segment. 
The code that accomplishes the 
sequence is near the top of both 
the FNCountFiles function and 
the GetFiles procedure. 


CHOOSING A FILE 


The second part of PICKER is the 
subroutine Choose, which uses 
subroutines and shared variables 
that are found in the Turbo Basic 
Database Toolbox. Choose dis- 
plays the contents of the array on 
the screen and allows the user to 
pick from among the displayed 
filenames. This straightforward 
subroutine displays as many 
names as it can, then lets you pick 
one by moving a reverse video bar 
up and down on the screen. The 
up and down arrows move the 
highlight bar up or down the list. 
The Home key goes to the top of 
the list, and the End key goes to 
the bottom. Study the code and 
you'll see that it’s easy to support 
additional keys, such as PgUp or 
PgDn. The logic for Choose can 
be summarized in the following 
pseudo-code: 
Display as many items as you can 
Start with the first one 

Do 


Get a keypress 
If Enter or Esc pressed then 


Done 
Else 
Move the highlight bar 
as required 
End if 


Loop until done 


When Choose is called, it 
assumes that the cursor is at the 


top left corner of the area to be 
used for input. The parameters 
passed to Choose are: 


Pick The number of the 
item actually picked by 
the user. 

Visible The number of items 


in the list that can be 
seen at one time. 

N The total number of 
items in the list. 

Choices$() A string array contain- 
ing the items to be dis- 
played and chosen 
from. 


Notice that nothing in the 
design of Choose limits it to the 
selection of filenames only. You 
can modify Choose to select any- 
thing that can be kept in a list in 
your programs, such as menu 
options, names, and so forth. 

Also notice that you can choose 
both the number of items in the 
list and the number of items that 
are visible at any one time on the 
screen. Choose will scroll the list 
up or down as needed when you 
move the highlight bar. 

Choose scrolls the screen with 
the Turbo Basic Database Tool- 
box’s Scroll subroutine, which 
uses the PC’s BIOS VIDEO service 
(interrupt 10H, subfunctions 6 and 
7) to scroll the screen one line up 
or down. Another subroutine, 
ClrArea, uses the Toolbox func- 
tion WriteScreenArea to clear an 
area of the screen that is desig- 
nated by the row and column of 
its top left and bottom right 
corners. The subroutine ClrEol 
simulates the Turbo Pascal func- 
tion of the same name, and also 
uses WriteScreenArea to clear a 
single line from the cursor to the 
edge of the screen. 

Choose contains a shared 
variable named EscPressed. This 
variable is set to the constant 
%True when the Esc key, rather 
than Enter, is used to exit the sub- 
routine. This process allows you 
to check whether the user has 
aborted a file selection session. 

The function GetKeyStroke is 
worth further explanation. This 
function is a Turbo Basic Data- 
base Toolbox subroutine that 
retrieves a keypress as an ASCII 
number, rather than as a string. 
For extended keys (such as the 
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CASE Ent.Home 
From=1 
Pick=1 
GOSUB DisplayChoices 
CASE Ent.End 
From=N 
Pick=N 
GOSUB DisplayChoices 
END SELECT 
LOOP UNTIL Done 
EXIT SUB 


DisplayChoices: 
' Display all the choices starting with From on the screen. 
' Clears the display area first. 
CALL ClrArea(Top,Bottom,Margin, 80) 
I=From 


LOCATE R,Margin 

PRINT Choices$(I); 

INCR I 

INCR R 
LOOP UNTIL I>N OR R>Bottom 
R=Top 
RETURN 


Highlight: 
' Highlight the current choice. 
' video. 
LOCATE R,Margin 
COLOR 0,7 
PRINT Choices$(Pick); 
RETURN 


Displays this in reverse 


Lowlight: 
' Lowlight the current choice before moving on. 
' choice in normal video. 
LOCATE R,Margin 
COLOR 7,0 
PRINT Choices$(Pick); 
RETURN 
END SUB 


Displays the 


SUB ClrArea(TopRow, BottomRow, LeftCol ,RightCol) 
' Clear an area of the screen using WriteScreenArea 
LOCAL NumberOfRows ,NumberOfCols,NumberOfChars,ClrText$,ClrAttr$ 
NumberOfRows=Bot tomRow- TopRow+1 
NumberOfCols=RightCol-LeftCol+1 
NumberOfChars=NumberOfRows*NumberOfCols 
ClrText$=STRING$S(NumberOfChars," ") 
ClrAttr$=STRINGS(NumberOfChars, &HO7) 
CALL WriteScreenArea(TopRow, LeftCol ,NumberOfRows ,NumberOfCols, _ 

ClrText$,ClrAttr$) 
END SUB 


SUB ClrEol 
' Clear a line from the cursor to the end using ClrArea 
CALL ClrArea(CSRLIN,CSRLIN,POS(0),80) 

END SUB 


' Main program 


CALL SernInit 

CALL InitEntry 

DIM FileNames$(100) 
COLOR 7,0:CLS 
LOCATE 1,1:PRINT "File Picker Demo"; 
LOCATE 3,1:PRINT STRING$(80, 196); 


' Required by ENTSUBS 
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Done=%False 
EntSpec$="" 
Prompt$="Drive and Directory: " 
FieldSize=80-LEN(Prompt$)-1 

bdo 


CALL PromptEntry(FieldSize, FieldSize,"",2,1,&HO7,&H70,CHR$(13),3,_ 


Prompt$,EntSpec$, Changed, Exi tKey) 
IF Changed AND LEN(EntSpec$)>0 THEN 
Spec$=EntSpec$+"\*.*" 
N=FNCountFi les(Spec$) 
IF N>O THEN 
LOCATE 24,1 
CALL ClrEol 
PRINT "Files lListed:";N 
CALL GetFiles(Spec$,FileNames$()) 
LOCATE 4,20 
CALL Choose(Pick,19,N,FileNames$()) 
IF NOT(EscPressed) THEN 
LOCATE 24,1 
CALL ClrEol 
PRINT "You chose ";FileNames$(Pick); 
ELSE 
CALL MinorErrorSound 
END IF 
ELSE 
LOCATE 24,1 
CALL ClrEol 
PRINT "No files found..."; 
CALL MinorErrorSound 
END IF 
ELSE 
Done=%T rue 
END IF 
LOOP UNTIL Done 
cLS 
END 


PICK A FILE 
continued from page 111 


function keys, Alt keys, and cursor 
pad keys), the second byte of the 
extended ASCII value is added to 
255. For example, the Home key, 
75, is translated as 326. When you 
include the Toolbox subroutines, 
you can use shared variables such 
as Ent.Home for these commonly 
used keycodes. If you aren’t build- 
ing strings out of the user’s key- 
presses, GetKeyStroke is the pre- 
ferred way to work with key- 
presses. 

The Toolbox subroutine 
PromptEntry, called from the 
main program of PICKER, 
retrieves the drive and directory. 
Normal video attribute (7H) is 
used for the prompt area, and 
reverse video (70H) is used for the 
input area. This powerful Toolbox 
subroutine makes it easy to han- 
dle the user’s input because it sup- 
ports color changes, field lengths, 
and even the editing keys. (The 
Turbo Basic Database Toolbox’s 
screen functions are described in 
“Turbo Basic Screens At Assem- 
bler Speed,” TURBO TECHNIX, 
March/April, 1988.) 


TAKE YOUR PICK 


The routines included in PICKER 
constitute a simple toolbox for 
searching for files using the DOS 
FIND FIRST and FIND NEXT ser- 
vices, and for picking items from 
lists. You can also break each of 
the two parts of PICKER out into 
its own $INCLUDE file for use in 
other programs. There’s plenty of 
room for improvement here, 
including defining the screen 
colors through variables, putting 
multiple columns of choices on 
the screen, and handling addi- 
tional movement keys. But the 
routines as written illustrate the 
basics well enough for you to 
move forward on your own. Use 
them in good health, and from 
now on don’t be shy about asking 
your users to pick a file. @ 


Marty Franz is a programmer who 
frequently writes on microcomputer 
topics. He lives in Kalamazoo, 
Michigan. 


Listings may be downloaded from 
CompuServe as PICKER.ARC. 
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Your ad should be here. 


SEPTEMBER/OCTOBER 1988 
ISSUE CLOSING DATE: JUNE 23 


Multitask Turbo Pascal applications under DOS ... learn how to 
use linked lists in Turbo C ... understand PAL procedure memory 
management ... save and load EGA screens from Turbo Basic ... 
add a pattern-matcher to the MicroStar editor from the Turbo 
Pascal Editor Toolbox ... learn about storing data in 286 extended 
memory ... our columnists, our critiques, and lots more! 


NOVEMBER/DECEMBER 1988 
ISSUE CLOSING DATE: AUGUST 25 


More on Turbo Pascal multitasking ... take the mystery out of 
structures and unions in Turbo C ... write a code-generating 
script in PAL ... emulate SQL in Turbo Prolog ... rotate Turbo 
Basic GET/PUT bitmaps in a hurry ... create custom disk format- 
ter programs in Turbo Pascal ... expert advice from our colum- 
nists, and much more! 


There’s only 


one way 
to reach 


a programmer— 


Use the 


programmers’ 
magazine: 


TURBO 
TECHNIX 


THE BORLAND LANGUAGE JOURNAL 


CALL NOW 
RESERVE YOUR 
TURBO TECHNIX 
SPACE TODAY! 


Office of the Publisher 
(408) 438-9321 


Publisher 
Marcia Blake 


Advertising Sales Manager 
John Hemsath 


Western Office 
(714) 858-0408 
Janet Zamucen 


New England/ 
Mid-Atlantic Office 
(617) 848-9306 
Merrie Lynch 
Nancy Wood 


Southern Office 
(813) 394-4963 
Megan Patti 


TURBO BASIC 


PLOTTER SUPPORT, 


TURBO STYLE 


Don’t rely on canned programs to do your plotting —send 
your own commands from any Turbo language. 


William H. Murray and Chris H. Pappas 


Many scientists, engineers,and mathema- 
ticians use plotters on a regular basis to 
output information from commercial pro- 
grams such as AutoCad, ASYST, smART- 
WORK, and Energraphics. Pen and ink 
drawings done on a plotter are crisp and 
neat. However, it’s often difficult to write your own 
software to take greater advantage of the plotter. For- 
tunately, many plotters now available respond to the 
Hewlett Packard Graphics Language (HPGL) com- 
mand set, which is summarized in Table 1. Describ- 
ing these commands in detail is beyond the scope of 
one article, but most plotter manuals discuss the 
commands in sufficient depth. 

What the manuals typically do not provide are 
language-specific programming examples. The best 
way to learn anything is by example, and here we 
provide simple examples of how to use the HPGL 


PROGRAMMER 


commands in all four Turbo languages. To take 
advantage of these four example programs, you need 
a plotter capable of understanding the HPGL com- 
mand set. HPGL is as close as we come to a plotter 
interface standard these days, and most low-end plot- 
ters support it. Plotter manufacturers usually provide 
chapters in their hardware documentation to help 
you interface their plotters with your programs, and 
these chapters should say if your plotter understands 
HPGL. (If you’re unsure about your plotter, contact 
the manufacturer directly.) 


GIVE US SOME KIND OF SINE 
The example plotter program is a popular graphics 
routine that plots a curve of SIN(X)/X. 
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Figure 1. A plot of the curve repre- 
sented by the function SIN(X)/X, as 
produced by the listings in this article. 


Most plotters communicate with 
your PC through a serial port. 
Before executing any of the exam- 
ple programs, you need to set the 
baud rate and other communica- 
tion parameters of one of your 
serial ports to match the require- 
ments of your plotter. In our case, 
the plotter requires a baud rate of 
9600, no parity check, 8 data bits, 
and | stop bit. We’ve used serial 
port COM1. Setting things up is 


continued on page 116 


Table 1. 


COMMAND 


EXAMPLE 


AA 2016,2016,90,5; 
AR 1016,1016,90,5; 
CA 3 

CI 250,5 

CP 2,-2 


DR 1 
DT*; bill* 


EA 1000,1000; 
ER 500,500 

EW 500,30,90,5; 
FT 3,50,45 

IM 19; 


IN 


IP 500,250,1500,1250; 


IW 500,0,625,250; 


LB THIS IS MY LABEL 


LT 25; 
OA 


OC 


PA 500,500; 
PD 
PR 500,500; 


PS 3; 

PT 5 

PU 

RA 600,600; 

RO 90; 

RR 600,600; 

SA 

SC 0,10365,0,7962; 
SI .6,.5; 

SL | (45 degrees) 
SM +; 


VS 15; 

WG 500,30,90,5; 
XT 

YE 


DESCRIPTION 


Draws arcs (absolute) 

Draws arcs 

Gets alternate character set 
Draws circle 

Character plot 

Gets standard character set 
Reactivates auto pen lift 

Sets plotter’s default function 
Direction of line lettering 
Deactivates auto pen lift 
Direction of line lettering 
Character (*) is terminator 

for label 

Rectangle at absolute coordinate 
Rectangle at relative coordinate 
Perimeter of a pie segment 

Fill instruction 

Reports unmasked 

program errors 

Reinitializes plotter 

Assigns new coordinates 
Boundary for plotting 

Draws a string of characters 
Line type, for style of line 
Outputs pen coordinates 

& physical status 

Outputs pen coordinates 

& logical status 

Actual coordinates & physical status 
Outputs first unmasked instructions 
Outputs size of plotter unit 
Upper and lower plotter area 
Outputs plotter identification 
Outputs options of plotter 
Current coordinates of P1 

and P2 

Output status byte 

Coordinates of window 

Moves pen to specified position 
Pen down 

Moves pen to relative 
coordinates 

Sets paper size 

Pen point thickness (mm) 

Pen up 

Shades rectangle 

Rotates plotter coordinates 
Shades relative rectangle 
Selects recent character set 
Scale 

Size of character set 

Slants character set 

Character and vector system 
Selects pen 

Width, height character size 
Selects most recent character set 
Horizontal and vertical ticks 
Designs symbols and characters 
Pen velocity 

Fills pie segment 

Draws vertical tick at position 
Draws horizontal tick at position 


Hewlett Packard Graphics Language commands. 
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LISTING 1: PLOT.BAS 


REM PROGRAM PLOT .BAS 


REM LOAD BLACK PEN AND KEEP IT UP 
LPRINT "IN SP 1" 


REM PLOT A SIN(X)/X CURVE IN BLACK 
FOR X=3 TO 1033 
Z=((X*10)-5182.5)*0.0035 
IF 2=0.0 THEN 2=0.1 
Y=(2000+3000*SIN(Z)/Z) 
LPRINT "PA", (X*10),,", CY), "PD* 
NEXT X 
LPRINT "PU" 


REM DRAW A BLUE BORDER AROUND WHOLE SIN(X)/X PLOT 
LPRINT "SP 6 PA 0,0 PD EA 10365,7962 PU" 


REM DRAW A RED LINE THROUGH MID POINT OF PLOT 
LPRINT "SP 2 PA 0,2000 PD PA 10365,2000 PU" 


REM DUMP PLOTTER BUFFER, ETC. 
LPRINT "PA 0,7962 SP" 


LISTING 2: PLOT.PAS 


PROGRAM PLOTC(INPUT, OUTPUT); 


USES Printer; 


VAR 
X,Y : Integer; 
Z : Real; 


PROCEDURE DRAWER; 


BEGIN 
(* LOAD BLACK PEN AND KEEP IT UP *); 
WRITELNCLST,'IN SP 1;'); 


(* PLOT A SIN(X)/X CURVE IN BLACK *); 
FOR X:= 3 TO 1033 DO 
BEGIN 
2:=((X*10)-5182.5)*0.0035; 
IF Z=0.0 THEN Z:=0.1; 
Y :=ROUND (2000+3000*SIN(Z)/Z); 
WRITELNCLST, 'PA ',(X*10),',',(Y),' PD;') 
END; 
WRITELNCLST, "PU; "); 


(* DRAW A BLUE BORDER AROUND WHOLE SIN(X)/X PLOT *); 


WRITELN(LST,'SP 6 PA 0,0 PD EA 10365,7962 PU;'); 


(* DRAW A RED LINE THROUGH MID POINT OF PLOT *); 


WRITELN(LST, SP 2 PA 0,2000 PD PA 10365,2000 PU;'); 


(* DUMP PLOTTER BUFFER, ETC. *) 
WRITELN(LST, 'PA 0,7962 SP;'); 


END; 
BEGIN 


DRAWER; 
END. 


LISTING 3: PLOT.C 


/* PROGRAM PLOT.C */ 


#include <stdio.h> 
#include <math.h> 
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PLOTTER SUPPORT 
continued from page 115 


simple via two invocations of the 
DOS MODE command: 

C>MODE COM1:9600,N,8,1,P 

C>MODE LPT1:=COM1 

You can replace COMI with 
COM2 in the two commands if 
you intend to use serial port 
COM2. The P (short for Printer or 
Plotter) in the first command 
avoids possible time-out errors; 
omit it if you intend to communi- 
cate with a remote communica- 
tions service rather than a desktop 
peripheral. 


PLOTTING BY EXAMPLE 


Listing 1 is a complete Turbo 
Basic program that generates the 
plot of the sine curve described 
earlier. Turbo Basic LPRINT com- 
mands direct program output to 
the printer port. The various 
HPGL commands are enclosed 
within the LPRINT statements 
(refer to Table 1 for more infor- 
mation about each command). 


_ HPGL is as 
close as we come to 
a plotter interface 
standard these 
days, and most 
low-end plotters 
support it. 


Listing 2 is an equivalent Turbo 
Pascal program. In this example, 
output is directed to the printer by 
using the LST device file in each 
Writeln statement. Otherwise, the 
program is structured very much 
like the Turbo Basic program. 

Listing 3 is a Turbo C program. 
In CG, there is no simple way to 
send output to the printer when 
using the printf command. It is 
much easier to write and compile 


the program so that the plotter 
commands are sent to standard 
output. You can then redirect stan- 
dard output to the chosen serial 
port using DOS command line 
output redirection. This process 
requires that you compile the pro- 
gram to a .EXE file and then leave 
the Turbo C programming envir- 
onment. When you are ready to 
execute the program, use the DOS 
redirection command: 


C>PLOT > PRN 


Once plotter 
commands are sent 
to standard output, 
you can redirect 
standard output to 
the chosen serial 
port using DOS 
command line 


redirection. 


Listing 4 completes the set of 
examples with a Turbo Prolog pro- 
gram that generates the same plot. 

Figure | is the sample plot 
generated by each program. The 
actual plot is in color, with a blue 
border and a red line through the 
midpoint of the plot, but it’s repro- 
duced here in black and white. It’s 
simple once you see how it’s 
done! @ 


Bill Murray and Chris Pappas are 
professors of computer science at 
Broome Community College. Together 
they have written six books for 
Osborne McGraw-Hill. Their book on 
the IBM PS/2 Model 80 will be 
released this summer. 


Listings may be downloaded from 
CompuServe as HPPLOT.ARC. 


main() 

\ 

int X,Y; 
float 2 


/* LOAD BLACK PEN AND KEEP IT UP */ 
printf("in sp 1;"); 


/* PLOT A SIN(X)/X CURVE IN BLACK */ 
for (x=1; x<1034; x++) 
{ 

2=((x*10.0)-5182.5)*0.0035; 

if (z==0.0) z=0.1; 
y=Cint)(2000.0+3000.0*sin(z)/z); 
printf("pa"); 

printf("%d", x*10); 

printf(","); 

printf("%d",y); 

printf("pd;"); 
> 
printf("pu;"); 


/* DRAW A BLUE BORDER AROUND WHOLE SIN(X)/X PLOT */ 
printf("sp 6 pa 0,0 pd ea 10365,7962 pu;"); 


/* DRAW A RED LINE THROUGH MID POINT OF PLOT */ 
printf("sp 2 pa 0,2000 pd pa 10365,2000 pu;"); 


/* DUMP PLOTTER BUFFER, ETC. */ 
printf("pa 0,7962 sp;"); 


LISTING 4: PLOT.PRO 


predicates 
plot(real) 
checkZ(real, real) 
drawer 


goal 
writedevice(printer), 
drawer, 
writedevice(screen), 
write("done"). 


clauses 
drawer: - 
write("in sp 1;"), | /* Load Black Pen */ 
plot(3), 
write("pu;"), 


/* Draw a blue border around the plot */ 
write("sp 6 pa 0,0 pd ea 10365,7962 pu;"), 


/* Draw a red line through the midpoint of the plot */ 
write("sp 2 pa 0,2000 pd pa 10365,2000 pu;"), 


/* Dump Plotter Buffer, etc. */ 
write("pa 0,7962 sp;"). 


plot(1034):-!. 
plot(X):- 
TempZ = ((X*10) - 5182.5)* 0.0035, 
checkZ(TempZ,Z), 
Y = (2000 + 3000* sin(Z) /Z), 
TenX = X*10, 
write("pa", TenX,",",Y,"pdz"), 
NewX = X+1, 
plot(NewX). 


checkZ(Temp, Val):- 
Temp = 0,!, 
Val = 0.1; 
Temp = Val. 
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TURBO BASIC 


BACKGROUND COLOR MAGIC 


You can trade those blinking 


characters for eight 


new background colors. Here’s how. 


Mark Novisoff 


If you’re like most programmers, you 
probably think that the PC can display 
only eight background colors in text 
mode. Not true—you can get 8 additional 
background colors on a color monitor, 
ww __ for a total of 16. One word of caution— 
these eight new colors come at the cost of blinking 
foreground characters. 

The text video attribute byte uses 4 bits for fore- 
ground color (giving us 16 colors), 3 bits for the 
background color (giving us 8 colors), and 1 bit indi- 
cating whether or not the foreground character is 
blinking. Listing 1 (MAGIC.BAS) reprograms the 
video controller to interpret the blink bit as back- 
ground color information. This allows us to use 4 
bits for background color, for 16 background colors. 

MAGIC also detects the presence of an EGA or 
VGA adapter, which is necessary because the method 
for reprogramming the controller differs depending 
upon which graphics board is installed. When a CGA 
is present, we simply do an OUT to the video con- 
troller chip. When an EGA or VGA is installed, we 
must use a BIOS service since the EGA/VGA con- 
troller is not 100 percent compatible with the CGA 
controller. We detect these adapters by calling two 
BIOS services—the first detects VGA adapters, and 
the second detects both VGAs and EGAs. If neither 
BIOS service recognizes the installed adapter, the 
adapter is a CGA. 

After MAGIC checks whether an EGA or VGA is 
installed, it displays characters in foreground colors 
from 0 to 15 against background colors from 0 to 7. 
At the point where MAGIC reprograms the video 
controller, the background cells beneath the blink- 
ing characters magically change to eight new back- 
ground colors—and the blinking stops. 

It’s really a small price to pay. @ 


WIZARD 


Mark Novisoff is the president of MicroHelp, Inc., and is 
the author of Mach 2 for Turbo Basic, an assembly lan- 
guage subroutine library. 


Listings may be downloaded from CompuServe as 
COLORS. ARC. 
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LISTING 1: MAGIC.BAS 


MAGIC.BAS by Mark Novisoff. 


This program demonstrates how you can display a total 
of 32 background colors on a color monitor. 


Make sure that you "zoom" the run window out to the full screen! 


Defint A-Z 
True = -1 
False = 0 
Reg 1, &H1a00 
Call Interrupt &H10 
Al = Reg(1) Mod 256 
If Al <> &H1A Goto No.Vga 
Bl = Reg(2) Mod 256 
lf Bl = 7 Goto Found.Vga 
If Bl <> 8 Goto No.Vga 
Found. Vga: 
Vga = True 
Goto Do.display 
No.Vga: 
Reg 1, &H1200 
Call Interrupt &H10 
Bl = Reg(2) Mod 256 
If Bl <> &H10 Then 
Ega = True 
End if 
Do.display: 
Cls 
For Foreground=0 to 31 
For Background=0 to 7 
Color Foreground, Background 
Print “aaa "; 
Next 
Next 
Print 
Print 
Color 7,0 
If EGA + VGA <> 0 Goto EGA ' If either one was detected 


This is a VGA specific BIOS call 


Get low byte (al register) 

If Al<>&H1a then there is no VGA 
Get low byte 

If Bl=7 or 8, then a VGA is there 
Not there 


*' No VGA, but maybe an EGA 
' EGA/VGA BIOS service 


' Get low byte 


‘ Then we have EGA 


For CGA Adapters 


Input "Press <Enter> to disable blink ", AS 
Out &H308, 9 ' for mono use Out &H3B8 
Input "Press <Enter> to enable blink ", AS 
Out &H3D8, &H29 ' for mono use Out &H3B8 
End 


EGA: For EGA/VGA Adapters 
Input “Press <Enter> to disable blink ", AS 
Reg 2,0 
Reg 1,&H1003 
Call Interrupt &H10 
Input “Press <Enter> to enable blink ", AS 
Reg 2,1 
Call Interrupt &H10 


' BIOS service to disable/enable blink 


Lots of software packages 
help you work; only one helps you 
work smarter... SideKick Plus! 


| SIDEKICK Plus 
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oving ahead takes more than 

hard work, it takes smart 

work. There are stacks of 
productivity software you can buy for 
your PC. But to work smart, you only 
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PAL’S TOOLS FOR FINANCIAL 


INFORMATION 


Money is no object when you write your financial analysis 


programs in PAL. 


Todd Freter 


No matter how obliquely we try to put it, 
at some level business programming is 
the technology of managing money. 
Apart from a simple program to manage 
a business contact file, few PAL applica- 
tions for business will not involve finan- 
cial programming of some sort. PAL is well-equipped 
to deal with financial matters, and in this article we 
will take a close look at PAL techniques involving the 
coin of the realm. 


PAL’S FINANCIAL FUNCTIONS 


Among the 126 predefined functions in PAL are 4 
functions devoted exclusively to financial analysis. 
Like functions in other programming languages, 
these financial functions take arguments and return 
single values. PAL’s financial functions are: 


PROGRAMMER 


©® Future value, FV: The future value of equal, regu- 
lar payments on a loan or to an annuity fund for 
a certain number of time periods. 

@ Payment, PMT: The periodic payment amount to 
pay off an amortized loan. 

@ Present value, PV: The present value of equal, 
regular payments on a loan or withdrawals on an 
investment for a certain number of time periods. 

® Net present value, CNPV: The value in current 
money of future cash flows associated with an 
investment. 

These four financial functions fall into two catego- 
ries: single-record financial functions, and multiple- 
record financial functions. 


SINGLE-RECORD FINANCIAL FUNCTIONS 


The single-record financial functions FV, PMT, and PV 
perform operations on one or more data items as 
arguments that together constitute a single-record 
occurrence of financial data. These functions do not 
operate on sets of values in a column. 


Future Value, FV. This calculation demonstrates the 
cumulative result of making payments to an annuity 


fund by showing what those payments, at the speci- 
fied interest rate, will yield after a given number of 
payments. PAL’s future value function is: 


FV(Num1 ,Num2 , Num3 ) 


Num is a numeric expression representing the peri- 
odic payment, Num2 is a numeric expression repre- 
senting the interest rate per period for which each 
payment is made (expressed as a decimal), 

and Num3 is a numeric expression 
representing 


_ Saas 
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the number of periods during 
which payments are made. 

Note that each of these argu- 
ments is a numeric expression. As 
in other programming languages, 
functions in PAL allow you to 
supply expressions that evaluate 
to numbers. 

PAL calculates future value with 
the formula: 


FV = p*((14+r)n-1)/r 


p is the payment amount, r is the 
nominal interest rate, and n is the 
number of payment periods. 

For instance, to calculate the 
future value of an annuity with a 
9.6 percent annual interest rate to 
which you make quarterly pay- 
ments of $325.39 for 15 years, run 
this PAL script: 

MESSAGE FV(325.39,0.024,60) 

SLEEP 10000 

The MESSAGE command dis- 
plays the result of the 
calculation. 


The SLEEP command gives you 
10 seconds to see that in 15 years 
you'll be sitting on the tidy sum of 
$42,700.87 (which isn’t bad, con- 
sidering that your total outlay is 
60 payments of $325.39, or 
$19,523.40). 

You can make this script more 
universal and friendly by using 
display statements and variables to 
contain user input for the func- 
tion’s arguments. The modified 
script is given in Listing 1, 
FUTURE.SC. 

Payment, PMT. This calculation 
determines the amount that must 
be paid every period to pay off an 
amortized loan for a given num- 
ber of periods at a specified inter- 
est rate. An amortized loan is a 
mortgage-type loan, in which 
interest and principal 

are paid 


off together, unlike consumer 
loans, such as credit accounts or 
automobile loans. You cannot use 
PMT to determine the payment 
on non-amortized loans. PAL’s 
payment function is: 


PMT (Num1 , Num2, Num3) 


Num] is a numeric expression 
representing the amount of the 
loan (principal), Num2 is a nu- 
meric expression representing the 
effective interest rate per period 
for which each payment is made 
(expressed as a decimal), and 
Num3 is a numeric expression 
representing the number of peri- 
ods during which payments are 
made. 

PAL calculates the payment 
with the formula: 


PMT = P*(r/(1-(1+r)-n)) 


P is the principal loan 
amount, r is the nominal 
interest rate per 
period (not per 
year!), and n 
is the 
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PAL FINANCIAL TOOLS 
continued from page 121 


number of payment periods in the 
term of the loan. 

For instance, to determine the 
monthly payment for a home 
equity loan of $30,000 at 10.5 per- 
cent per year for 15 years, with 
payments due at the end of each 
month, run the following script: 
MESSAGE 

PMT (30000, (.105/12),(15*12)) 
SLEEP 10000 
The monthly payment will be 
$331.62. To calculate the total cash 
outlay of the loan (principal and 
interest, exclusive of loan fees), 
multiply the payment amount by 
the number of payment periods. 
In this case, $331.62 X 180 = 
$59,691.60. 

You can easily generate a script 
that accepts user input for the 
PMT function’s arguments and 
displays the value that PMT 
returns. 


Present Value, PV. This function 
represents the initial or principal 
value of an amortized loan. PV 
tells you how high a mortgage you 
should apply for, based upon the 
payment you can afford to make, 
the effective interest rate, and the 
number of payment periods in the 
loan contract. PAL’s present value 
function is: 

PV(Num1 , Num2, Num3 ) 

Numl is a numeric expression 
representing the periodic payment 
amount, Num2 is a numeric ex- 
pression representing the effective 
interest rate per period for which 
each payment is made (expressed 
as a decimal), and Num3 is a 
numeric expression representing 
the number of periods in which 
payments are made. 


PAL calculates present value 
with the formula: 
PV = p*((1-(1+r)-n)/r) 
p is the principal loan amount, r 
is the nominal interest rate per 
period, and n is the number of 
payment periods in the term of 
the loan. 
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For instance, if you can afford a 
monthly mortgage payment of 
$675.00, and your research shows 
the two best loans are for 11.5 per- 
cent for 15 years or 12.25 percent 
for 30 years, run the following 
script to determine the amount of 
principal for which you can apply 
under either loan: 

x = PV(675, (0.115/12), (15*12)) 

= PV(675, (0.1225/12), (30*12)) 
"Apply for ", x, 

"at 11.5% for 15 years." 
2? “Apply for ", y, 

"at 12.25% for 30 years." 

SLEEP 10000 


<< 


_ multiple- 
record function is 
the natural com- 
panion of a rela- 
tional database 
system, which stores 
data in tables 

made up of rows 


(records) and 


columns (fields). 


The result tells you to apply for 
$57,781.71 on the 15-year loan and 
$64,414.76 on the 30-year loan. 
Now use the FV function to deter- 
mine the relative costs of both 
loans (the quantity of principal 
plus interest). 


MULTIPLE-RECORD 
FINANCIAL FUNCTION 


PAL’s multiple-record financial 
function CNPV performs an op- 
eration on values that together 
constitute a multiple-record oc- 
currence of financial data. A 
multiple-record function that 
operates on a set of like values is 
the natural companion of a rela- 
tional database management sys- 
tem, which stores data in tables 
made up of rows (records) and 
columns (fields). CNPV performs 


operations such as the calculation 
of the average value in a set of 
values. CNPV’s name begins with 
a C to indicate that it operates on 
a set of values in a column. This 
distinction reflects the nature of 
the Paradox database in which the 
financial information is stored. 


Net Present Value, CNPV. This 
function evaluates investment op- 
portunities based upon the time 
value of money being invested. 
Net present value analyzes an 
investment based on a series of 
real or projected cash flows per 
time period, as a function of the 
interest paid to finance the invest- 
ment. If the net present value cal- 
culation returns a positive value, 
the investment should be profit- 
able. PAL’s net present value func- 
tion is: 

CNPV(TableName, FieldName, Number ) 


TableName is a string (not an 
expression) representing the 
name of the table with a numeric 
field whose entries represent in- 
vestment cash flows, FieldName is 
a string (not an expression) repre- 
senting the name of the numeric 
field in TableName containing 
cash flows for regular periods, 
and Number is a numeric expres- 
sion (expressed as a decimal) 
representing the effective interest 
rate per period for which each 
payment is made. Passing the 
name of a non-numeric field in 
FieldName causes a PAL script 
error. 

PAL calculates net present value 
with the formula: 


CNPV = sum(p=1 to n) of Vp/(1+r)p 


p is the period associated with a 
cash flow amount, Vp is the cash 
flow in the pth period, r is the 
nominal interest rate per period, 
and n is the number of payment 
periods for which there is cash 
flow. 

Consider an apartment build- 
ing, with income from its units 


PERIOD Month  NetCash 
1 Jan -200 
2 Feb 2000 
3 Mar -150 
4 Apr 1000 
5 May 600 
6 Jun 750 
7 Jul 200 
8 Aug -175 
g Sep 450 

10 Oct 1200 
11 Nov -75 
12 Dec -150 


Figure 1, A table of cash flow values 
for one year. Each value consists of 
income plus expenses for a particular 
month of the year in question. 


and costs associated with each 
apartment or for the building as 
a whole. Let’s assume you can 
secure a loan at 11.75 percent to 
finance the apartment building. 
Let’s also assume that you can 
project the monthly cash flow 
based on rental income and 
expenses over the next twelve 
months, as shown in the Paradox 
table in Figure 1. To evaluate the 
net present value of this invest- 
ment’s cash flow at 1.15 percent 
per month, run the PAL script 
NETPV.SC in Listing 2. NETPV.SC 
evaluates the cash flow for the 
investment and determines its net 
present value. If the result of the 
calculation is positive, the script 
embeds it in an encouraging mes- 
sage; if negative, the script 
embeds it in a cautionary mes- 
sage. In this case, the net present 
value is $5138.68, and the program 
exhorts you to invest. Of course, 
much more information goes into 
a decision to invest money, but 
net present value is a useful tool 
for evaluating the cash flow pro- 
jections of the investment. 

PAL’s net present value calcula- 
tion presumes two things: 
e The initial cash flow before 

payments start is zero; and 


® Payments are made at the end 
of the payment period. 


The apartment building example 
assumes that you buy the property 
with no down payment. If the 
investment involves an initial cash 
flow I, then you simply add it to 
the calculated net present value: 
I1+CNPV(TableName, FieldName, Number ) 


If you make a down payment, it 
must be added as an initial (nega- 
tive) cash flow to the net present 
value. If the down payment is 
greater than $5138.68, then your 
investment in the building may 
not be profitable for the first year. 
You can continue projecting fu- 
ture cash flows and include 


Net present value 
analyzes an invest- 
ment based on a 
series of real or 
projected cash 
flows per time 
period, as a func- 
tion of the interest 
paid to finance the 


e 
investment. 
BUYERS 

Name MaxDownPmt MaxMonthlyPmt 
Feldman 35000.00 1900.00 
Ruzicka 19500.00 1750.00 
Grijalva 22000.00 1750.00 
Chung 44000.00 1750.00 
Bedrosian 29000.00 1750.00 


Figure 2. A table listing the maximum 
possible down payment and monthly 
payment for a list of home buyers. 


them in a net present value calcu- 
lation to determine when the 
investment will become profitable. 


USING PAL’S FINANCIAL 
FUNCTIONS 


Let’s incorporate PAL’s financial 
functions into a simple real estate 
application. Based on a minimum 
of information about buyers, 
agents can identify optimal 
financing for a home purchase 
using either or both of two 

simple PAL scripts: Listing 3, 
DOWNPMTSSGC; and Listing 4, 
PAYMENTSSC. 

These scripts work with two 
tables, buyers and lenders. The 
buyers table, as shown in Figure 2, 
contains three fields: 


© Name identifies the buyer (or 
buyers) with a single surname. 

® MaxDownPmt contains the 
maximum down payment the 
buyer(s) can afford. 

© MaxMonthlyPmt contains the 
maximum payment the buy- 
er(s) can manage each month. 
The lenders table, as shown in 

Figure 3, has six fields: 


® Lender identifies a lending 
institution by name. 

©® DownPct contains the percen- 
tage of the purchase price 
required as a down payment 
for the loan. 

© Rate contains the fixed rate of 
interest on the loan expressed 
as a percentage. 

@ Term contains the term of the 
loan expressed in years. 

® Points contains the number of 
points that the borrower must 
pay for the loan. 

© Fees contains the loan fee for 
the particular loan. 
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LENDERS 

Lender DownPct Rate Term Points Fees 

Barney’s Mortgage 17.5 12.25 30 1.5 500.00 
Barney’s Mortgage 20 11.75 15 1.5 500.00 
Honest Abe’s Loans 15 13 30 2 450.00 
Honest Abe’s Loans 15 12.5 15 2 450.00 
Debtor’s Bank 20 11.75 15 1.5 550.00 
Debtor's Bank 20 12.5 30 15 550.00 


Figure 3. A table of loan term information from various lenders. 
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LISTING 1: FUTURE.SC 


a0,0 ?? “Enter payment amount:" 
@0,36 ACCEPT "n" TO amount 
21,0 ?? "Enter annual rate:" 
1,36 ACCEPT "n" TO rate 
a2,0 ?? “Enter term (number of years):" 
@2,36 ACCEPT "n" TO term 
23,0 ?? "Enter number of payments per year:" 
3,36 ACCEPT "n" TO payments ; e.g., to convert yearly rates 
; for monthly or quarterly payments 
answer = FV(amount, rate/100/payments, term*payments) 
a5,0 7? "If you pay $", amount, " ", payments, 
" times per year at ", rate, "% interest for ", term, 
" years," 
26,0 ?? "the future value will be $", answer, "." 
SLEEP 10000 


LISTING 2: NETPV.SC 


= CNPV("building", "NetCash", .0115) 
IF x > 0 
THEN MESSAGE "Net present value is ", x, ", so go for it!" 
ELSE 
MESSAGE "Net present value is ", x , ", so don't touch it!" 
ENDIF 
SLEEP 10000 


LISTING 3: DOWNPMT.SC 


password "onlynames" ; permit access to Name field only 
view "buyers" ; put buyers table on workspace 
moveto field "Name" ; move cursor to Name field 
wait table ; display protected table to user so 
; that user can select name of buyer 
prompt "Move cursor to name and press F2 for report." 
until "F2" ; select name where cursor is 
n = [Name] ; store current value inn 
; withdraw Name-only access to buyers 


; table and clear all passwords 
unpassword "onlynames" 
menu {Tools} {More} {Protect} {ClearPasswords} 
password "readfields" ; permit access to all fields 


view "buyers" put buyers table on workspace again 
moveto field "Name" move cursor to Name field 
locate n find the name browsed and chosen by user 
; create output file based on name 
; of user and assign file name to f 
Noy" +n "dwn"! 
[maxdownpmt] 
[maxmonth | ypmt] 


assign buyer's MaxDownPmt to x 
assign buyer's MaxMonthlyPmt to y 
Write report header to file that 
identifies Pens and stated down payment 
print file f "Report for buyer: ", n, "\n\n", 
"Based on your stated maximum say payment, $", x, "\n", 
"consider the following financing: \n\n" 
view "Lenders" ; put lenders table on workspace 
scan "Lenders" perform following calculations on all 
; records of lenders and write results to 
file, record by record - 
; calculate down payment corrected for fees, 
points, and "reserve" fund stored in prin 
prin = ((x * 100/[lenders->downpct] * .95) * 
(100 - [lenders->points])/100) - [lenders->fees] 
; with correct loan amount (prin), use PMT 
; function to calculate the monthly payment 
pay = pmt(prin, ([lenders->rate]/100)/12, [lenders->term]*12) 
if pay <= y ; if buyer can afford this monthly payment 
then ; then write that information to file 
print file f "You can finance $", prin, " at ", 
[lenders->rate], "% for \n", [lenders->term], 
" years with a monthly payment of $", pay, 
" from \n", [lenders->lender], ".\n" 
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PAL FINANCIAL TOOLS 
continued from page 123 


Because the buyers table con- 
tains sensitive information about 
each buyer's finances, passwords 
are applied so that only the Name 
column can be browsed with the 
WAIT TABLE command. In this 
way, when either script is played, 
the Grijalvas will not see how 
much the Feldmans can afford to 
put down on a house. Once the 
buyer’s name is selected, a differ- 
ent password allows the script to 
read the values that the user can- 
not directly access. 


Because the 
buyers table con- 
tains sensitive 
information, pass- 
words are applied 
so that only the 
Name column can 
be browsed with the 
WAIT TABLE 


command. 


Two simple PAL scripts match 
prospective buyers with realistic 
financing. Listing 3, Downpmt, 
evaluates each of the lenders’ 
plans in terms of the buyer’s 
stated down payment. The pro- 
gram then determines how much 
money the buyer could borrow on 
the basis of the down payment 
under each plan, and tests wheth- 
er the buyer can afford the 
monthly payments for the plan, 
based on the buyer’s stated 
budget. 

Listing 4, Payment, evaluates 
each of the lenders’ plans in 
terms of the buyer’s stated month- 
ly payment. Payment then deter- 


mines how much money the 
buyer could borrow on the basis 
of the monthly payment under 
each plan, and tests whether the 
buyer can qualify for the loan, 
based on the buyer’s down 
payment. 


More elaborate 
formatting of the 
output report is 
always an option, 
and should be 
added to any 
commercial 


application. 


Both scripts assume that the 
buyers have not included loan 
points and fees in estimating their 
down payments. The scripts also 
reduce the buyer’s stated down 
payment by five percent to accom- 
modate unanticipated expenses 
that often crop up in the purchase 
of a home. (This five percent ad- 
justment is arbitrary and can be 
modified as the PAL programmer 
sees fit.) Downpmt and Payment 
write the results of their evalua- 
tions into DOS files with simple 
formats. The formatting of this 
information is simple to keep the 
scripts short and their use of 
PAL’s financial functions clear. 
More elaborate formatting is 
always an option and should be 
added to any commercial 
application. 

These scripts illustrate how 
PAL’s financial functions can pro- 
vide the heart of a convenient 
script that supports real financial 
and commercial situations. @ 


Todd Freter is Senior Writer/Editor at 


Ansa Software. 


Listings may be downloaded from 
CompuServe as PALFIN.ARC. 


else ; if buyer cannot afford this, write also 

print file f "The monthly payment $", pay, " at ", 
[lenders->rate], "% for \n", [lenders->term], 
" years from", [lenders->lender], “ exceeds your stated \n", 
"budget of $", [buyers->maxmonthlypmt], ".\n" 

endif ; close affordability test 

endscan ; conclude scan operation 

; withdraw read-only access to buyers 

unpassword "readfields" 

clearall ; clear both tables from workspace 


LISTING 4: PAYMENT.SC 


password "onlynames" 
view "buyers" 


; permit access to Name field only 
moveto field "Name" : 


pe 
put buyers table on workspace 
move cursor to Name field 
display protected table to user so 
that user can select name of buyer 
prompt "Move cursor to name and press F2 for report." 
until "F2" ; select name where cursor is 
n = [Name] ; store current value inn 
withdraw Name-only access to buyers 
table and clear all passwords 
unpassword "onlynames" 
menu {Tools} {More} {Protect} {(ClearPasswords} 
password "readfields" ; permit access to all fields 
view "buyers" ; put buyers table on workspace again 
moveto field "Name" move cursor to Name field 
locate n find the name browsed and chosen by user 
create output file based on name 
of user and assign file name to f 


wait table 


Yor! + n+ “J pmt" 
[maxdownpmt] 
[maxmonth lypmt] 


; assign buyer's MaxDownPmt to x 
; assign buyer's MaxMonthlyPmt to y 
; Write report header to file that 


; identifies ae and stated monthly payment 


print file f "Report for buyer: “en, “\n\n*, 
"Based on your stated maximum monthly payment, $", y, 
"consider the following financing: \n\n" 
view "Lenders" ; put lenders table on workspace 
scan "lenders" perform following calculations on all 
records of lenders and write results to 
file, record by record - 
calculate down payment corrected for fees, 
; points, and "reserve" fund stored in prin 
prin = pv(y, (Llenders->rate] /100)/12, {lenders->term] *12) 
; calculate the loan amount for which buyer 
; could afford the monthly payments 
(.95 * prin * [lenders->downpct]/100 * (100 - 
[lenders->points] )/100) - [lenders->fees] 
calculate down payment corrected for fees, 
; points and "reserve" based on the loan 
amount that the buyer's monthly payment 
could carry 
if downpay <= ; if buyer can afford this down payment 
then ; then write the information to the file 
print file f "You can finance $", prin, " at ", 
[lenders->rate], "% for \n", tlenders->term) , 
" years with a down payment of $", downpay, "\n", 
" and a monthly payment of $", y, " from", 
[lenders->lender], ".\n" 
else ; if buyer cannot afford this, write also 
print file f "The required down payment of $", downpay, 
"to finance ", prin, " at ", [lenders->rate], 
"% for \n", [lenders->term], " years from", 
[lenders->lender], " exceeds your stated \n", 
"maximum for a down payment of $", x, ".\n" 
endif ; close affordability test 
endscan ; conclude scan operation 
; withdraw read-only access to buyers 
unpassword "readfields" 
clearall ; clear both tables from workspace 


“ \n" 5 


downpay = 
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BUSINESS LANGUAGES 


BUILDING AN ADDRESS 
DATABASE WITH SPRINT 


Build a database right into your word processor—in the word 


processor’s own language. 


Neil Rubenking 


Sprint is subtitled “The Professional 
Word Processor,” but it’s much more than 
that—Sprint’s macro language is as pow- 
erful as any programming language. If 
you're familiar with C or Forth, you'll rec- 
— ognize parts of Sprint’s macro language. 
However, other parts of the language are designed 
especially for word processing, and are quite differ- 
ent. For example, Sprint has 16 Q-registers instead of 
string variables; each of these registers holds any 
amount of text up to an entire document. 

Besides the obvious word processing functions, 
Sprint’s macro language invokes software interrupts, 
and reads or writes any memory location or port. As 
an example, you can force Caps Lock on with this 
Sprint macro: 


40h->PeekSeg (Peek 17h | (1 << 6)) -> Peek 17h 


This get-to-the-hardware power lets Sprint take full 
control of the PC when necessary. In the process, 
Sprint accomplishes things that one would not ex- 
pect of a word processor, such as the creation and 
maintenance of a macro-based address database. 


PROGRAMMER 


THE DATABASE 


The macro file DATABASE.SPM (Listing 1) uses 
Sprint’s menuing and text manipulation abilities to 
create a handy address database that you can load 
with names of frequent correspondents. This data- 
base macro lets you insert name and address infor- 
mation into your current document by choosing the 
name you want from a pop-up Sprint menu. Mainte- 
nance of the database is handled by loading and 
running DATABASE.SPM through the Macros item 
on the Utilities menu (Alt-U); this displays a menu 
with the two options, Add New and Delete. Since 
deleting doesn’t make sense until the database 
contains entries, I'll discuss Add New first. 


ADDING A NEW ENTRY 

When you select the Add New menu entry, the 
AddNew macro asks you for information via a 

prompt in the highlighted bar at the bottom of 


Sprint’s screen. AddNew first requests the name that 
is to appear on the menu, and then prompts you to 
specify three lines of text to be associated with that 
name. This text can be a person’s name plus two 
lines of address information, or any other three lines 
of text—it’s up to you. Now for the magic—the Sprint 
code modifies itself to include the new name choice 
as part of the macro source code in the file 
DATABASE.SPM. 

The next time you run the database macro, the 
name you previously entered appears as a new 
choice on the menu. When you select that name, the 
macro inserts the name and its three associated text 
lines into your document at the current cursor posi- 
tion. You can keep adding names to the macro— 
when the macro contains more names than can fit 
on the screen, simply page through the additional 
choices as you would with any other Sprint menu. 
An onscreen menu produced by the database macro 
is shown in Figure 1. The three-line address at the 
top of the document was inserted by pressing the 
Enter key when the corresponding name was 
highlighted. 


HOW IT WORKS 


Sprint is a new language to almost everyone, so 

I'll walk through Listing 1 step-by-step. The file 
DATABASE actually holds three separate macros. 
The first macro, AddNew, adds names to the data- 
base by modifying the last macro, which is database. 
The database macro is a simple Sprint menu. The 
title of the menu follows the word “menu” itself, and 
parentheses enclose the menu choices. Each menu 
choice consists of a line that appears in the menu, 

a number of Sprint commands, and a comma to 
separate the menu choice from the next choice. 
The remaining macro, DeleteOne, removes records 
from the database. Let’s look at the database macro 
after one name has been added to it, as shown in 
Figure 2. 


continued on page 128 
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Introducing Paradox 386. 

Optimized for 386 environments 

and up to 5 times faster 
than Paradox 2.0 


a 
aoom ~ 


a 


esigned exclusively for 

80386-based systems, 

Paradox® 386 runs up to 
5 times faster than Paradox 2.0. 
It’s that much faster because it 
accesses your full linear address 
space, which in English means it 
uses all the memory you or your 
company paid for when you put 
together your 386 systems. 

With Paradox 386, the old 

640K limits are a thing of the past. 


“Sottware Digest Ratings Report, March 1986, July 1987. 

“*Customer satistaction is our main concern; it within 60 days of purchase this product 
does not perform in accordance with our claims, call our customer service department, 
and we will arrange a refund. 

sa iS a Borland international company Other brand and 
product names are 
Copyright ©1988 
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It runs in the 

DOS environment 
and is a modern must 
for power users con- 
fronted with very large 
tables (tens of thousands 
of records or more) 
and/or large applica- 
tions. Paradox 386 
makes more ambitious 
mainframe-type applica- 
tions feasible on the PC 
because it addresses up 
to 16 megabytes of 
memory. 

But back to speed. 
Paradox processes data 
32 bits at a time instead of just 16 
bits at a time, so you race rather 
than run. 


Paradox 2.0 and 386. 
The same but different 
Paradox 386 gives you all the 

functionality, power, and flexibility 
that earned Paradox the Software 
Digest top-rating for PC relational 
databases* Like Paradox 2.0, the 
all-new Paradox 386 gives you 
the speed and power to: 

* Query multiple tables simultaneously 


« Use an unlimited number of 
selection criteria 


¢ Do pattern matches and relational 
operations on tables with up to 
2 billion records 
And Paradox 386 makes fast work 
of big operations like: 
¢ Retrieving data with large single 
or multi-table queries 
« Paging through screens of infor- 
mation as you view large tables 
¢ Sorting tables with several 
thousand records 
* Developing applications with the 
Paradox Personal Programmer 386 
¢ Running large memory-intensive 
applications 


Paradox 386 also lets you share 
data on local area networks with 
workstations running different 
network versions of Paradox. 


Make the most of your fast 
new 386 hardware with our 
fast new 386 software 

Get up to speed with Paradox 
386. Your 386-based system has 
the racing engine, Paradox 386 
is the racing fuel. 

For information on upgrading 
from Paradox 2.0 to 386, call 
(800) 548-7543. 


Works with the Intel® Inboard™ 


60-Day Money-back Guarantee ** 


For the dealer nearest you or 
a brochure, call (800) 5438-7543 


— 


CKR ER LACE ONAL 


Figure 1. A Sprint screen showing the menu created by database. 


database : menu "Address Database" ( 


"Add New person " AddNew, 
"Delete a person" DeleteOne, 
"Joe" 

"Joe Jones" 

"\n123 Pleasant St." 
"\nAtown, USA\n") 


Figure 2. The database macro, after one name has been added. 


SPRINT DATABASE 
continued from page 126 


The first menu choice is still 
Add New; selecting this choice 
runs the macro AddNew, as de- 
scribed before. Delete is still the 
second menu choice. However, 
the menu now contains a third 
choice, Joe. If you select Joe, 
Sprint executes the commands fol- 
lowing that line up to the comma 
(or to the final parenthesis). In 
this case, the commands are text 
strings that Sprint inserts in the 
document. Note the \n in the last 
two lines—this command stands 
for “new line.” Without this com- 
mand, the macro inserts the fol- 
lowing text into your document 
as one line: 


Joe Jones123 Pleasant St.Atown, USA 


As you add more people to the 
database, you'll create similar 
entries for each new person. 

The AddNew macro uses one 
of Sprint’s multiple buffers to hold 
the text of the macro file. With 
the command 2 open, we locate 
DATABASE.SPM and read it into 


a buffer. At the end of the macro, 
the command close closes the 
temporary buffer and returns to 
the previous buffer. The 2 before 
open tells Sprint to search the 
path for the requested file, if that 
file is not found in the current 
directory. Naturally, the macro 
quits with an error message if it 
can’t find DATABASE.SPM. 

After the open command is 
issued, the text of DATABASE.SPM 
is stored in a buffer. Before 
adding a new name, we have to 
make sure there’s enough room 
for it. In theory, names could be 
added until the menu lines total 
more than 4K, but Sprint’s 42K 
macro space would probably be 
overrun first. To avoid running 
out of macro space, the database 
is arbitrarily limited to 75 names. 
We need to count the lines in the 
database macro to be sure it 
doesn’t already contain 75 names. 
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First, find the beginning of 
the database macro. The string 
“database:” occurs three times: 
twice in search macros, and the 
third time as a macro name itself. 
To locate the third occurrence, 
use the command 3 repeat, which 
makes Sprint repeat the search 
three times. The current line 
number is stored in the variable 
holdnum. 

Next, locate the last nonempty 
line of the macro. toend goes to 
the end of the file and performs 
a character search in reverse for 
a right parenthesis, using the 
command: 


r (')!' csearch) 


After the search, the line number 
of the found line is stored in line. 
If this line number is less than or 
equal to the sum of holdnum plus 
4 lines for each of 75 entries, the 
macro has room for more entries. 
Otherwise, the program sends a 
message and quits. 

If room is available for a new 
entry, delete the final parenthesis 
using del. Next, insert a comma, a 
new line, and several spaces in 
the form of this string: 


“ F \n " 


In general, you tell a macro to 
insert text in a document by 
simply placing the text in quotes. 
You can also explicitly call the 
macro insert. To insert FOO, for 
example, you would type: 


insert "FOO" 


In addition, you need to use 
insert to insert the contents of a 
Q-register into a document. Be 
sure to surround the request with 
parentheses to make it clear that 
this is not a request to fill the 
Q-register, as in the example 
below: 


(insert Q1) 


You can’t insert every character 
this way, though. For example, the 
quote character delimits strings. 
To insert a literal quote character, 
precede it with a backslash, as 

in Ss. 

Input from the user is needed 
for the next steps. In Sprint, it’s 
easy to read text into a Q-register. 
The macro set QO fills QO with 
the user’s response to the prompt 
“Enter text:”. To specify a differ- 
ent prompt, use the message 
macro to put the prompt on the 
status line first. Before all but the 


second input request, clear QO 
with the command set Q0 “”. 
Since the actual address name 
is almost certainly related to 

the menu name, leave the name 
in QO. 

Notice the string \\n in three 
places. The doubled slash charac- 
ter is no accident—in Sprint, the 
slash is the signal for a special 
character. \n means new line, \t 
means tab, and so on. The idea 
is to insert the two literal char- 
acters \ and n into the text in the 
Q-register, so that they can be 
added to the source code of the 
database macro. Sprint interprets 
\n (with a single slash) as a re- 
quest to insert a new line; the ex- 
tra slash in \\n tells Sprint not to 
interpret the character that fol- 
lows the slash. 

After all the lines are written 
to the buffer, restore the final pa- 
renthesis and write the changed 
text back out to the macro file 
DATABASE.SPM. This step is 
handled by the command Write 
“%, which tells Sprint to write the 
current buffer to the current file- 
name. The last step is to activate 
the newly modified macro with 
the command mread “database”. 


DELETING AN ENTRY 


The DeleteOne macro lets you 
use any part of a name or address 
to select an entry to delete. Sup- 
pose you want to delete Joe Jones, 
but you can only remember that 
he lives on Pleasant Street ... or 
was it Pheasant? Enter “P?eas” at 
the prompt; when the macro finds 
a match, it displays the whole line 
and asks you to confirm. Suppose 
that it displays “Alice Pleasance 
Liddell.” Since that’s not the entry 
you want, answer the prompt with 
NO. The next match that you see 
is “123 Pleasant St.”, which is the 
one you want. If you confirm the 
deletion, DeleteOne removes this 
entry and then reloads the 
changed macro file. 

DeleteOne locates 
DATABASE.SPM and finds the 
start of the database macro within 
the file, just as AddNew does. 
Then DeleteOne prompts you for 
the name that you wish to delete. 
The search occurs within one big 


continued on page 130 


;DATABASE Macro set 
int holdnum 


AddNew : ;MACRO to add a new person 
if (2 open "database.spm") { 
; Get to the start of the database macro 
3 repeat { 1 search "database :" } 
line->holdnum 
toend r (')' csearch) 
; Be sure there aren't TOO many already. 
; We set a limit of 75 names 
if line <= 4*75+holdnum ¢€ 


> 


del "\n " 

set QO." 

message "Name to appear on menu: " 
set Q0 $ 

; to allow first letter conflicts: 
mark (to Q0 while !isend ToLower) 
OO\ tees Cinsert ao) "\"$\n u" 
Message "Name line for address: " 
set Q0 $ 

Woy tone Cinsert Qo) "\A"S\n " 

set QQ." 

message "Street line: " 

set Q0 $ 

"\"\\n" Cinsert Q0) "\"$\n " 
set QO "™" 

message "City,State,Zip line: " 
set Q0 $ 

book ad, OU bas Cinsert Qo) WAnN\YS)" 
write "x" 

close 

mread "database" 


else € 


> 
> 


else € 


close 
message "\nOnly 75 entries allowed -- sorry. " 


bell message "\nFile DATABASE.SPM not found" 


> 


DeleteOne : ; MACRO to delete a person 
set QO "" 
message "Delete who: " 


(set Q0) 
if (2 open "database.spm") { 


» big IF 


; Get to the start of the database macro 
3 repeat { 1 search "database :" } 
down down 
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SPRINT DATABASE 
continued from page 129 


DO { ; Offer matching entries for deletion DO loop. Notice that break occurs 
if !(3 search QO) { ; 2 means allow wildcards 


bell message "Sorry, " (message Q0) “ ne places, which are the oats 
message " NOT FOUND" om the loop. The loop ends if it 
0 wait close break fails to find the string or if you 
2 ; confirm that the string it finds is 
set Q ue 
correct. When you confirm an 
; Put the whole found LINE in Q2 entry for tao the macro 
(tosol copy toeol Q2) tosol oe age 
(message "Delete ") deletes all four lines. In order to 
(message Q2) do this, the macro has to locate 
if ask" (Y/N)" € ; if yes delete the beginning of the entry. (Re- 
setmark member, the macro can match 


; Get to the start of the matched entry > : 
r ('," esearch) down tosol ;; added tosol! any of the entry’s four lines.) The 


; Now delete it following line of commands first 
4 repeat € delete (toeol c) } searches backward to the comma 
i If we erased the final ")", restore it. that ends the previous entry, and 
if !(')" esearch) € then moves down to the start of 
toend r (',' csearch) del ")" the next text line: 
} : r (',' csearch) down tosol 
write "x" i 
close The deletion of the actual text 
mread "database" information in the macro is per- 
, break formed by this line of code: 
else € 4 repeat { delete (toeol c) } 
; Not that one? Move down a line so we . 
S dontt. ind te deme ond Abaial Delete toeol simply deletes to the 
down tosol end of the line. To delete the line- 
} end character, add the c to direct 
> ; big DO the macro to delete one more 
Nig iF character past the end of visible 
bell message "File database.SPM not found" text. : i 
} After making the deletion, 
; DeleteOne saves and reloads 


ie autes a. Waenii Siren Databawn’ DATABASE.SPM, just as AddNew 

: ata . A 

"add New person " AddNew, ‘3 did. Of course, if no name was 
"Delete a person" DeleteOne) selected for deletion, the reload- 

ing process is skipped. 


GIVE IT A TRY 


The AddNew macro is ready to 
roll—you can type it in or down- 
load it from CompuServe and run 
it. Since the names are in a stan- 
dard text file, they can even be 
edited with Sprint. The ability to 
edit the macro file also allows you 
to export names from a separate 
database program, such as 
Paradox, and then insert them 
into the macro—but don’t forget 
that 75-name limit! 


Neil Rubenking is a professional Pas- 
cal programmer and writer. He is a 
contributing editor for PC Magazine, 
and can be found daily on Borland’s 
CompuServe Forum answering Turbo 
Pascal questions. 


Listings may be downloaded from 
CompuServe as SPDBAS.ARC. 
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Lone 
ast issue, we looked at 
using pre- and postcon- 
ditions to implement 


abstract data types, and 
created a standalone module that 
implements a tic-tac-toe board. We 
provided a listing of the module, 
and used the module to write a 
program that plays tic-tac-toe. You 
can plug the tic-tac-toe module 
into a program of your own de- 
sign, without having to copy any 
other portion of the tic-tac-toe 
program, by simply declaring in 
your program that you’re using 
the module. 

By contrast, I recently tried to 
extract the routines that handle 
the creation, display, and selection 
of menus out of a text editor’s 
source code. This task initially 
appeared easy, because the high- 
est level menu routines were set 
off in a separate module. It turned 
out, however, that those routines 
called procedures in several other 
modules; the routines also used a 
number of global variables that 
were used by still other modules. 
Attempts to extract those proce- 
dures and variables showed ob- 
scure linkages to yet other proce- 
dures and variables. In the end, I 
gave up, feeling as though I were 
trying to remove the entire ner- 
vous system—intact—from an 
animal. 

The difference between last 
issue’s tic-tac-toe module and the 
menu module described above 
lies in their degrees of coupling. 
Coupling refers to the intercon- 
nectedness between two pieces of 
code involving parameters, global 
variables, etc. Most often, one of 


How loosely are you coupled? 


Bruce F. Webster 


the pieces of code is in a program, 
and the other piece is located in a 
subroutine or collection of sub- 
routines used by that program. 
Coupling is usually a function of 
how communication takes place 
between the pieces of code, and 
which procedures are called by 
both pieces. 


Coupling refers 


to the intercon- 
nectedness between 
two pieces of code 
involving parame- 
ters, global vari- 
ables, and so on. 


Code is often described as 
being “loosely coupled” or “tightly 
coupled.” The tic-tac-toe module 
was loosely coupled with the tic- 
tac-toe program. It’s an easy task 
to extract a loosely coupled module 
from a program for use in an- 
other program. It’s also easy to 
write another version of that 
module and then drop the new 
version in place of the first one, as 
long as each version’s interface is 
the same. 

By contrast, the menu routines 
in the second example are tightly 
coupled, both to the editor and to 
one another. They make extensive 
use of the editor’s global variables, 
and call many procedures used by 


other sections of the editor. 
Hence, it’s almost impossible to 
extract the menu-handling rou- 
tines in a form that can be used 
by any other program. Also, it’s 
difficult to write a new implemen- 
tation of the menu routines that 
could be used in place of the cur- 
rent routines. 

Does this mean that loose cou- 
pling is always good, or that tight 
coupling is always bad? Not neces- 
sarily. In some situations, tight 
coupling is more convenient; in 
other situations, it’s essential. But 
before we explore tight coupling 
further, let’s look more closely at 
loose coupling. 


LOOSE COUPLING 


Imagine for a moment that you 
want to enhance your stereo sys- 
tem, which currently has several 
components, including an ampli- 
fier, a turntable, and a tape deck. 
You decide to add a compact disc 
player, so you connect it to the 
system with a couple of audio 
cables. When you get a two-drive 
cassette deck, you simply unplug 
the old cassette deck and plug in 
the new one. Finally, you decide 
that vinyl is passé and you remove 
your turntable from the system 
altogether. 

Throughout this process your 
stereo system continues to work 
just fine. Adding the CD player 
gives the system new capabilities 
without diminishing existing ones. 
Swapping the tape decks increases 
the functionality of the tape deck 
subsystem. Removal of the turn- 
table shrinks the stereo system's 
size and functionality, but doesn’t 
affect any other functions in the 
system. 


continued on page 132 
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continued from page 131 


This stereo system is loosely 
coupled. The CD player (a module 
of the system) connects with the 
amplifier (and thus with the rest 
of the system) via two simple 
cables. For the most part, the CD 
player’s make, model, and features 
are irrelevant to the amplifier, 
which only knows about the CD 
player’s two cables that carry the 
sound for the amplifier to process 
and send to the speakers. Like- 
wise, the CD player knows noth- 
ing about the amplifier other than 
that the amplifier expects two 
cables. The CD player has no con- 
nection at all with the speakers, 
even though they ultimately play 
(make audible) the signals. 

What's the benefit of this loose 
coupling? As shown, you can up- 
date, modify, or rearrange your 
stereo system with a minimum of 
hassle or problems. As newer and 
better components come along, 
you can upgrade your system 
accordingly. (My modest system, 
which has been evolving for sev- 
eral years now, has none of its 
original components left.) 

Getting a little closer to home, 
coupling applies to computer 
hardware as well. Consider the 
typical DOS-based system, which 
has a series of expansion slots 
based on a standard interface that 
allows you to upgrade and modify 
your system. The system usually 
has a socket for an optional math 
coprocessor, and you can often 
upgrade other aspects of the sys- 
tem as well, such as its disk drives. 

Loose coupling works well with 
hardware; does it work equally 
well with software? Yes—but as 
with hardware, loose coupling 
in software requires some fore- 
thought and discipline. The result, 
though, can be well worth it. 

Consider, for example, the case 
of a large software project that 
involves several programmers. 
Each programmer has responsibil- 
ity for a section of the finished 
program. The software design can 
be separated into loosely coupled 
modules, with the interface for 
each module clearly specified. 
Each programmer can then work 
independently to develop modules 
according to the specifications, 
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much as a host of companies can 
manufacture CD players based on 
the specifications for input (the 
standard compact disc format) 
and output (two channels of 
sound). If all the programmers 
follow the agreed-upon specifica- 
tions, the resulting modules will— 
in theory, at least—easily plug 
together to form the finished 
program. 


~ Global variables 
between two pieces 
of code tend to bond 
tightly; to make the 
code more loosely 
coupled, these 
global variables 
typically need to be 
replaced by 
parameters. 


The same principle applies 
when you're doing all the pro- 
gramming yourself. By breaking 
the program into separate, loosely 
coupled modules, you make your 
overall design task easier. You also 
make it easier to recycle your code 
into other programs, since you 
can plug in those modules else- 
where with little or no modification. 


HOW TO DO IT 


We've established that loose cou- 
pling is desirable under some cir- 
cumstances. The next question is: 
How do you achieve it? 

Think again about the stereo 
system example. The CD player 
and the amplifier contain very 
complex electronics, yet the two 
are not connected with a mass of 
wires. Two cables suffice, since the 
amplifier cares only about the left 
and right channels coming out of 
the CD player. 

You must similarly limit the con- 
nections in your code, because the 
more connections you include, 
the more tightly your code will be 


coupled. Possible connections are 
mutually referenced constants, 
data types, variables, and sub- 
routines—any of these connec- 
tions between several pieces of 
code can cause tight coupling, 
and decoupling the code can be 
messy. Global variables between 
two pieces of code tend to bond 
more tightly; to make the code 
loosely coupled, these variables 
typically need to be replaced by 
parameters. 

Let’s start by talking about a sin- 
gle subroutine. The first step in 
making it loosely coupled with the 
rest of the code is to pass all infor- 
mation via parameters, rather 
than through global variables. 
Consider the sort routine in List- 
ing 1. This routine presumes that 
the program contains two global 
variables: List (an array of type 
Integer) and Count (an integer 
variable). It sorts the integers in 
List into ascending order, using 
the selection sort method. This 
routine is tightly coupled to the 
rest of the program, and it can 
only sort the one integer array 
(List). To use Listing 1 in another 
program, that program must also 
have an integer array named List, 
as well as an integer variable 
named Count. 

Now look at the version of the 
sort routine in Listing 2. This ver- 
sion expects to be passed two 
parameters—an array and the 
number of elements in the array. 
Some coupling is still going on, 
since Listing 2 expects the global 
types ListType and BaseType to 
be declared; data types, however, 
tend to be less binding than vari- 
ables. In fact, Listing 2 is set up so 
that you can declare BaseType to 
be any one of a number of types 
in your program—Char, Byte, 
ShortInt, Integer, Word, LongInt, 
Real, Single, Double, Extended, 
Comp, any enumerated data type, 
or any string type. All you must do 
is declare BaseType appropriately, 
with ListType declared as an array 
of BaseType (with some specific 
limit), and the procedure still 
works correctly. Note, however, 
that ListType has a fixed length, 
and that it’s the only type of array 


you can pass to Sort within the 
program. 

Finally, look at the sort routine 
in Listing 3. This routine is com- 
pletely decoupled from the pro- 
gram, and requires no global dec- 
larations whatsoever. Listing 3 is 
restricted to arrays of four base 
types: ShortInt, Integer, LongInt, 
and Real. The type is indicated by 
the Size parameter, which should 
be 1, 2, 4, or 6, respectively. If Size 
holds any other value, then the 
nested function LessThan always 
returns a value of False, leaving 
the array untouched. There is also 
an arbitrary (though very large) 
limit on the array size, based on 
constraints imposed by the Turbo 
Pascal compiler. The rewards, 
however, are twofold: you can 
drop this routine into any pro- 
gram without having to modify 
either the program or this proce- 
dure; and you can pass an array 
of any length (up to the indicated 
maximum) to this routine. 

So much for decoupling a sin- 
gle procedure; what about a whole 
group of them? This can be either 
easier or more difficult, depend- 
ing upon what you’re decoupling. 
In many cases, any shared con- 
stants, data types, variables, and 
subroutines can all be put into a 
single, separate unit or module, 
along with the routines to be 
decoupled. 

In the last issue, for example, 
we looked at TicTac, a unit for 
playing tic-tac-toe. This unit im- 
plements a constant (GLim), a 
few data types (Move, Location, 
Game), and a number of proce- 
dures and functions. TicTac 
makes no external references, 
and so can be dropped into any 
program. 

We also looked at the Moves 
unit, which allows the computer to 
play tic-tac-toe. This unit is not as 
loosely coupled—it depends upon 
the TicTac unit for data types and 
subroutine calls. Moves presents 
two variables and one procedure 
to the main program; the program 
uses them to generate the neces- 
sary moves. The Moves unit, how- 
ever, doesn’t depend upon any- 
thing from the main program, so 
this unit can also be dropped into 
another program if the TicTac 
unit is in that program also. 


Finally, the GameIO unit 
depends upon both the TicTac 
unit and the standard CRT unit— 
Gamel0O requires the presence of 
both of these units in order to 
function. In turn, GameIO pre- 
sents to the main program a cou- 
ple of data types and four proce- 
dures, which can be used to 
display the game and to prompt 
for moves. 


me Tightly coupled 
code—both custom- 
ized and inline—is 
almost always 
faster than more 
general, loosely 
coupled code. 


These units are loosely coupled 
to each other, and even more 
loosely coupled to the main pro- 
gram. The main program “knows” 
almost no details of how the tic- 
tac-toe game is implemented, how 
moves are generated, or how the 
game in progress is displayed. If 
you modify the Moves unit to play 
a more (or less) intelligent game, 
the program itself won’t be aware 
of the changes. 

By contrast, changing from the 
tic-tac-toe program’s text-based 
display to a graphics display would 
require more work, since the 
GamelIO unit and the main pro- 
gram are more tightly coupled in 
their mutual use of the CRT unit 
and in their presumption of a text 
display. To loosen the bonds, we 
would need to add a clear-screen 
procedure and a write-string 
procedure to GamelIO. All game 
I/O would then be directed 
through the unit, and we could 
switch to a graphics display with- 
out making any changes to the 
main program. 


TIGHT COUPLING 

If loose coupling is so great, why 
don’t you do it all the time? There 
are three basic reasons: speed, 
memory, and convenience. Let’s 
look at each of them. 


Speed. Compare the sort routines 
in Listings 1 and 3. Which do you 
think executes more quickly? Ca- 
sual examination indicates that 
the version in Listing 1 is faster; 
this version has less overhead and 
uses fewer instructions to perform 
the same operation. Also, the code 
generated to reference parameters 
is often more complex than that 
generated to reference global vari- 
ables, due to stack manipulation, 
indirect addressing, and similar 
issues. Actual tests show that the 
routine in Listing 1 sorts a list of 
1000 random integers more than 
three times faster than the routine 
in Listing 3. 

Must this always be the case? 
Essentially, yes. Tightly coupled 
code—both customized and 
inline—is almost always faster 
than more general, loosely 
coupled code. The issue then 
becomes one of tradeoffs: Is the 
increase in speed sufficient to jus- 
tify the loss of flexibility? That’s a 
decision you must make for your- 
self, case by case. 


Memory. The second reason for 
considering tightly coupled code 
is memory. Again, a quick compar- 
ison of Listings 1 and 3 reveals 
which one produces more ma- 
chine code. In addition to produc- 
ing more code, general routines 
often require more data space as 
well in order to handle a wider 
variety of situations, especially 
error conditions. 

Even more significantly, passing 
all information as parameters can 
create a lot of stack overhead, es- 
pecially if you have a large amount 
of global information that is 
needed by many different rou- 
tines. At the very least, you need 
to pass addresses or pointers to 
those data structures; this process 
does use less space, but can still 
significantly affect stack overhead, 
especially if you have any recur- 
sive routines. 

Convenience. The last reason to 
use tightly coupled code is conve- 
nience. Looking at Listings 1 and 
3, which do you think would be 
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LISTING 1: SORT1.PAS 


procedure Sort; 
€ 
preconditions: List is an array[1..Limit] of Integer 
Count is of type Word 
and in the range 0..Limit 
postconditions: The elements 1..Count of List are sorted 
in ascending order 
> 
var 
Top,Min,K,Temp : Integer; 
begin 
for Top := 1 to Count-1 do begin 
Min := Top; 
for K := Top+1 to Count do 
if List{K] < List [Min] 
then Min := K; 
if Top <> Min then begin 
Temp := List [Top]; 
List[Top] := List [Min]; 
List[Min] := Temp 
end 
end 
end; { of proc Sort } 


LISTING 2: SORT2.PAS 


procedure Sort(var List : ListType; Count : Word); 
{ 
preconditions: BaseType is a type for which the operators 
z=, <>, and < all are defined 
ListType = array[1..Limit] of BaseType 
Count is in the range 0..Limit 
postconditions: The elements 1..Count of List are sorted 
in ascending order 
> 
var 
Top,Min,K : Integer; 
Temp : BaseType; 
begin 
for Top := 1 to Count-1 do begin 
Min := Top; 
for K := Top+1 to Count do 
if List{K] < List [Min] 
then Min := K; 
if Top <> Min then begin 
Temp := List{Top]; 
List(Top] := List[Min]; 
List[Min] := Temp 
end 
end 
end; { of proc Sort } 
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easier to write off the top of your 
head? Which appears easier to 
debug and get running? (As a mat- 
ter of fact, I did have a bug in the 
routine I wrote for Listing 3: I 
started the three local arrays with 
an index of 0 instead of 1. Took 
me a while to track the problem 
down.) 

Again, if your routines need to 
access a lot of data structures, it 
can be painful to have long 
parameter lists to every procedure 
and function. Of course, not all 
code needs to be decoupled; rou- 
tines that are naturally grouped 
together can communicate via 
global (to them, at least) data 
structures. 

Some years back, I coauthored 
a large, realtime, high-resolution 
graphics computer adventure 
game. The final code was around 
15,000 lines of Pascal and another 
5,000 lines of assembly language. 
Because of severe constraints on 
memory and a need for as much 
speed as possible, my set of 
loosely coupled units became ever 
more tightly coupled as time went 
on. Case in point: the graphics 
library, which started out as a 
general graphics library that did 
lots of error checking and little 
game-specific graphics. Once 
speed and memory constraints 
began to crop up, though, we 
started pruning—many safeguards 
were removed; code that pre- 
sumed a lot about the rest of the 
game was added; and references 
were made to global data struc- 
tures that were shared with the 
rest of the game. The final graph- 
ics library was so tightly coupled 
to the game itself as to be useless 
for any other application without 
very significant rewriting—but it 
achieved its purpose of making 
the game both possible and fast 
enough to be accepted by its 
users. 

Each unit in the game was 
tightly coupled with the main pro- 
gram. A few very large global data 
structures were used to contain 
the complete game state. This 
approach, of course, made it easy 
to save and restore the game in 
progress by simply writing the 


data structures to disk to be saved, 
then reading them back in to be 
restored. Passing the data struc- 
tures through all the different lay- | | procedure Sort(Size,Count : Word; var List); 
ers of procedure calls would have € 
been ridiculous, especially given 
the tight memory and speed con- 


LISTING 3: SORT3.PAS 


preconditions: Size has a value of 1, 2, 4, or 6 
Count is in the range 0..Limit 


List is an array of type ShortInt, Integer, 


straints. Instead, the data struc- 
tures were assumed global and 
were used freely by all routines. 

There was, however, significant 
decoupling between units due to 
the simple fact that we couldn’t fit 
more than a few units into mem- 
ory at any one time. Each unit or 
set of units handled a distinct, 
nonoverlapping function. When 
that function (such as ship repair) 
took place, the required unit was 
loaded in from disk; when the 
function was done and another 
function (such as navigation) took 
place, the old unit was flushed 
out, and the new one was 


postconditions: The elements 1..Count of 


a 

var 
SList 
IList 
LList 
RList 
Top,Min,K 


function LessThan(I,J : Word) 


LongInt, or Real 
the upper bound of Limit and the type of List 
are determined by Size as follows: 


Size max 


1 
2 
4 
6 


value of Limit type of List 
ShortInt 
Integer 
LongInt 
Real 

List are sorted 


in ascending order 


array(1..64000] of ShortInt 
array(1..32000) of Integer 
array[1..16000] of LongInt 
array[1..10667] of Real 


Word; 


absolute List; 
absolute List; 
absolute List; 
absolute List; 


: Boolean; 


- begin 
loaded in. case Size of 
LessThan := SList[I] < SList{J]; 
STAY LOOSE LessThan := IList{I] < IList(J]; 


As a general rule, loose coupling 
is preferable to tight coupling. 
Loose coupling allows for modu- 
lar design, structured program- 
ming, and recycled code, and 
generally makes it easier to debug, 
maintain, and upgrade programs. 
Loose coupling is based largely on 
heavy use of parameter lists, the 
avoidance of communication via 
global variables, and the forma- 
tion of separately compiled 
modules or units. 

Tight coupling, even though it 
introduces problems, is sometimes 
necessary and desirable. You can 
generally use tight coupling to 
improve performance, reduce 
code size, and add convenience. 
However, these benefits need to 
be weighed against increased 
complexity in debugging, mainte- 
nance, and upgrading. Whether 
you decide upon loose coupling 
or tight coupling, you'll find that 
the use of good design and coding 
techniques does wonders. @ 


Bruce Webster is a computer merce- 
nary living in California. He can be 
reached via MCI Mail (as Bruce 
Webster) or on BIX (as bwebster). 


Listings may be downloaded from 
CompuServe as COUPLE. ARC. 


LessThan 
6 : LessThan : 
else LessThan 


end 


end; { of locproc 


procedure Swap( 


Gr=1 
(J-1 
0 


to Size-1 


Temp := SLi 


SList[I+K] : 
SList[J+K] : 


end 


end; { of locproc 


begin 


= LList{I] 
= RList[I] 
:= False 

LessThan } 


I,J : Word); 


: Word; 


ShortInt; 


: char; 


)*Size; 
)*Size; 


st [I+K]; 
Temp 
Swap } 


SList [J+K]; 


< LList(JJ; 
< RList(JJ; 


do begin 


for Top := 1 to Count-1 do begin 


Min := Top; 
for K 


:= Top+1 to Count do 


if LessThan(K,Min) 


then Min 


:= K; 


if (Min <> Top) 
then Swap(Min, Top); 


end; 


end; { of proc Sort } 
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Creati 


like analogies. Analogies 
help me bridge the concep- 
tual gap between what I 
know and what I’m strug- 
gling to learn. When I encoun- 
tered a list in Turbo Prolog for the 
first time, I immediately looked 
for an analogous concept in a 
procedural language—and picked 
the array. At first, my analogy 
between Turbo Prolog’s list and 
the array worked well. I soon 
found, however, that drawing 
parallels between procedural and 
declarative languages can be dan- 
gerous. Armed with my analogy, I 
expected the list to perform in the 
same way that an array performs. 
Instead, I discovered that an array 
handles programming activities 
that are difficult to do with a list. 
These differences became more 
apparent when I wanted to search 
through a large list and needed to 
improve the search strategy. A 
binary search would have been 
ideal, but this search method 
requires individual elements to be 
addressed directly. However, list 
elements by nature are accessed 
sequentially. (For more informa- 
tion about lists, refer to “What’s In 
a List,” elsewhere in this issue). 
Fortunately, with the marriage 
of Turbo Prolog and Turbo C, you 
can combine the power of list pro- 
cessing with the strength of arrays. 
In this article, we’ll look at lists 
and arrays from both sides of the 
fence. We'll examine ways to 
represent a Turbo Prolog list in 


Editor’s Note: Due to the very recent 
announcement of Turbo Prolog 2.0, we 


were unable to reflect 2.0 in this article. 
Note that some of the techniques de- 
scribed are specific to Turbo Prolog 1.x. 
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a work of art often means a 


Michael Floyd 


Turbo C, and see how to convert 
the list to an array and back to a 
list again. Finally, we'll present an 
example that sorts and searches a 
list using Turbo C’s qsort and 
bsearch routines. 


LISTS IN TURBO C 
Internally, Turbo Prolog repre- 
sents a list in memory as a linked 
list. Each record in the linked list 
contains three fields. The first 
field, which is one byte in size, is 
the list functor. The second field 
is the actual element in the list; 
the size of this field is the number 
of bytes that corresponds to the 
element type. The third field is 
a pointer (represented as a far 
pointer) to the next element in 
the list; this field’s size is four 
bytes. The three fields are repre- 
sented below as a data structure 
in Turbo C: 
typedef struct ilist { 

char functor; 

int value; 

struct ilist *next; 

> intlist; 
functor indicates the type of ele- 
ment that is referenced by the list 
record. If functor = 1, the record 
is a list element; if functor = 2, 
the record is a special value that 
indicates the end of the list. value 
is the actual element being refer- 
enced, and next is another ilist 
that references the next element 
in the list. 


CONVERTING A LIST TO 
AN ARRAY 


To convert a list to an array, we 
need to know how many elements 
are in the list. We must also know 
the data type of the list in order to 
allocate space for the array to be 
created. Once the array is created, 


blending of media—and of tools. 


convert the list by copying ele- 
ments from the list to the array. 
To do this, we'll create the func- 
tion ListToArray, which takes two 
arguments. The first argument is a 
pointer to the list to be converted, 
and the second argument points 
to the resulting array. The func- 
tion itself returns an integer value 
that corresponds to the number of 
elements in the list. This example 
uses a for loop to tally the number 
of elements in the list: 


int ListToArray(intlist *list, 


€ 


int **ResultArray) 


intlist *savelist = 
int *array; 
int i=) 0: 
for(i=0; list->functor == 1; 
list = list ->next) 
i++: 
array=palloc(i*sizeof(int)); 
list = savelist; 
for(i=0; list ->functor==listfno; 
list=list->next) 
array [it++]=list->value; 
*Resul tArray=array; 
return(i); 
> 


list; 


Next, we must allocate space 

for the array on the stack. As al- 
ways, use the routines provided in 
CPINIT.OBJ to manage the heap 
and stack in order to guarantee 
that heap space and stack space 
are handled using Turbo Prolog’s 
rules. The palloc routine allocates 
space on the global stack. 


Once the list has been con- 


verted, we can process the array in 
any manner we choose. In order 
to get the results back to the 
Turbo Prolog module, consider 
ArrayToList, which appears 
below. This function reverses the 
process and converts the array to 
a list: 


void ArrayToList(int array[],int n, 
intlist **list) 
Gint iz 
for (i=0; i<n; i++) 
{ 
intlist *p = *list 
= palloc(sizeof(intlist)); 


p->functor = listfno; 
p->value = arrayLi]; 
list = &(*List)->next; 
> 


€ 
intList *p = *list 
= palloc(sizeof(char)); 
p->functor = nilfno; 
> 
> 


ArrayToList converts an array 
to a Turbo Prolog list, using palloc 
to allocate memory on the global 
stack for each element of the list, 
and then builds the list by travers- 
ing through the array. Notice that 
the last element of the list is spe- 
cial—in effect, this element says, 
“T am the last element, because 
the value at p>functor is nilfro.” 
This last element is very important 
and must be specified. 

There is one final point: 
ArrayToList receives its list from 
the Turbo Prolog calling module 
via a pointer (to the list), and 
passes the result list back as a 
pointer to a pointer. Turbo Prolog 
gets the list from the address spec- 
ified by the pointer to the list. 


SORTING A LIST 

As mentioned earlier, we some- 
times want to search efficiently 
through large lists of data. With 
the techniques implemented so 
far, we can pass a list to Turbo 

C and convert it to an array. 
Now, we’ll use Turbo C to search 
through the array and retrieve a 
particular item. 

A number of search algorithms 
are available, but I prefer using 
the capabilities that are already 
built into a language. Turbo C 
implements the library routine 
bsearch to perform a binary 
search. Although a binary search 
expects the data to be sorted in 
ascending order, this is not a 
problem—we can use the library 
routine qsort to perform a quicker 
sort (an optimized quick sort) on 
the array before it’s passed to 
bsearch. Let’s look at the sort 
routine first. 

In Turbo C, we’ll define a func- 
tion, callable from Turbo Prolog, 


to perform the following actions: 
take a list from Turbo Prolog, con- 
vert the list to an array, pass the 
array to qsort, and convert the 
sorted array back to a list that is 
then returned to Turbo Prolog. 
This Turbo C function is shown 
below: 
void sortlist_O(IntList *InList, 
IntList **OutList) 
€ 
int n, *Array; 
n = ListToArray(InList, &Array); 
qsort(&Array [0] ,n,sizeof(int), 
compare); 
ArrayToList(Array,n,OutList); 
> 
Since the function is being called 
from Turbo Prolog, that function 
is defined as void. Note that (as 
always) an _0 has been appended 
to the function name to coincide 
with Turbo Prolog’s naming con- 
ventions. After the variable decla- 
rations, ListToArray is called to 
perform the conversion. We 
assign the number of elements in 
the list (returned by the function) 
to n. 
qsort takes four arguments: the 
address of the first element in the 
array, the number of elements in 
the array, the size of each element 
in the array, and the name of a 
function that is defined by the 
programmer. The purpose of this 
programmer-defined function is 
to compare two elements and 
then return a value based on the 
results of that comparison. qsort 
calls the comparison function suc- 
cessively to compare two individ- 
ual elements until all of the ele- 
ments in the array have been 
sorted. Depending on how the 
comparison function is written, 
the array can be sorted in ascend- 
ing or descending order. This 
compare function sorts in as- 
cending order: 
int compare(void *p1, void *p2) 
{ 
return(*(int *)p1-*Cint *)p2); 
2 


To see how compare is used, con- 


sider two elements to be sorted: 32 


Items compared Returns 
‘pl< "2 s——ts«éin‘intege 
*pl = = *p2 0 

*pl > *p2 


and 19. compare takes 32 as the 
first argument and 19 as the 
second argument, and then takes 
their difference (32 - 19 = 13). 
The positive value indicates 

that pl is greater than p2, and 
the values are swapped. Table 1 
shows the possible results of a 
comparison. 

Once the array is sorted, the 
final task is to convert the array 
back to a list (ArrayToList) and 
pass the list back to Turbo Prolog. 


SEARCHING A LIST 


Now that we’ve sorted a Turbo 
Prolog list, let’s use Turbo C’s 
bsearch to search the list for par- 
ticular items. Again, create a call 
to a function. The process is sim- 
ilar to that used on sortlist, but 
add an argument that specifies the 
element to be searched for in the 
list. Because there is no need to 
pass a list back to Turbo Prolog, 
the outlist parameter has been 
removed: 
void search_O(IntList *InList, 
int *key) 
‘ int n, *Array, *found; 
n = ListToArray(InList, &Array); 
found = (int *) bsearch(&key, 
&Array[0],n,sizeof (int), 
compare); 
if (found == 0) 
€ 
fail_cc(); 

> 

We give the Turbo C function 
some Turbo Prolog flavor by 
allowing search_0 to either suc- 
ceed or fail, based on the results 
of the search. By calling Turbo 
Prolog’s fail_ce library routine, 
the call to search fails if bsearch 
does not find the element being 
searched for. 

In PSORT-PRO (Listing 2), the 
find clause is called to search for a 
specified element in the array. 
find calls the Turbo C search func- 
tion. find is nondeterministic, so if 
search fails, Turbo Prolog back- 


continued on page 138 


an integer < 0 


an integer > 0 


Table 1. A list of possible values returned by compare. 
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LISTING 1: CSORT.C 


void _bsearch(void *key, void *base, int nelem, int width, 
int (*femp)()); 


void _qsort (void *base, unsigned nelem, unsigned width, 
int (*fcmp)(const void *, const void *)); 
#define qsort _qsort 
#define bsearch _bsearch 
#define listfno 1 
#define nilfno 2 


void *palloc(unsigned); 


typedef struct ilist ¢ 
char Functor; 
int Value; 
struct ilist *Next; 
} IntList; 


int ListToArray(IntList *List, int **ResultArray) 
{ IntList *SaveList = List; 
int *Array; 
int i = 0; 
/* Count list items. */ 
for(i=0; List->Functor ==listfno; 
List = List ->Next) 
i++; 
/* Allocate stack space. */ 
Array = palloc(i*sizeof(int)); 


List = SaveList; 
/* Copy list to array. */ 
for(i=0; List ->Functor==listfno; List=List->Next) 
Array [i++] =List->Value; 


*Resul tArray=Array; 
return(i); 
if 


void ArrayToList(int Array[],int n,IntList **List) 
int: 2 
/* Allocate a record for each element. */ 
for (i=0; i<n; i++) 
{ IntList *p = *List = palloc(sizeof(IntList)); 
p->Functor = listfno; 
p->Value = Array[i]; 
List = &(*List)->Next; 


/* Allocate the last record in the list. */ 


IntList *p = *List = palloc(sizeof(char)); 
p->Functor = nilfno; 


/* Compare two items in an array */ 
int compare(void *p1, void *p2) 
{ 
return(*(int *)p1-*Cint *)p2); 
> 


/* Sort a Turbo Prolog List */ 
void sortlist_O(IntList *InList, IntList **OutList) 
€ 
int n, *Array; 
n = ListToArray(Inlist, &Array); 
qsort(&Array [0] ,n,sizeof(int),compare); 
ArrayToList(Array,n,OutList); 
> 
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tracks to the second find clause, 
which informs the user that the 
element being searched for is not 
in the list. 


ON THE TURBO 

PROLOG SIDE 

The program in Listing 1 
(CSORT.C) implements all of the 
techniques discussed so far. List- 
ing 2 (PSORT-PRO) is the Turbo 
Prolog module that orchestrates 
the sorting and searching. As al- 
ways, Turbo Prolog must be the 
main module. 

Starting with the goal, 
PSORTPRO first calls cpinit to 
initialize the memory manage- 
ment routines. Then run is in- 
voked to get the list items from the 
user. List items are asserted into 
the Turbo Prolog database as they 
are entered. Once the user termi- 
nates the list (by entering -999), 
findall is used to collect all the 
database entries into a list. The 
list is then passed to the sortlist 
function created earlier. 

Once the list is sorted, we create 
a window displaying the sorted 
list, and pause so that the user can 
examine the list. The user is then 
prompted to enter another value, 
which is passed to the find clause. 
As mentioned earlier, find imme- 
diately calls search (written in 
Turbo C), passing the list sorted by 
sortlist and the value to search for 
in the list. If search succeeds, a 
message is displayed indicating 
that the value was found in the 
list. If search fails (via fail_cc in 
the Turbo C function), Turbo 
Prolog backtracks to the next find 
clause and displays a message that 
the element was not found. 


PUTTING IT ALL TOGETHER 
I won’t go into all of the agoniz- 
ing details of the link process 
here. If you read “Language Con- 
nections” regularly, you probably 
have this step memorized by now! 
If you want to know more about 
the link process, refer to any of 
the earlier “Language Connec- 
tions,” or consult the Turbo C 
User’s Guide. 

Remember to use the Large 
memory model when compiling 


the Turbo C module. Also, don’t 
forget to set the Generate under- 


bars compiler option OFF, and /* Search a sorted list for a specified value */ 


Use register variables OFF. Al- void search_O(IntList *InList, int *key) 
though not required, I like to { 
set Jump optimization ON. ee piel ao pees 
; : = ListToArray(InList, &Array); 
oy SAN ARS ae eg Cpe a bsearch(&key, &Array [0] +n, sizeof(int),compare); 
such as TLINK.EXE, which is pro- { 
vided on the Turbo C disk. The , fail_cc(); 


files to be linked (in order) are: 


@ INIT-OBJ—Turbo Prolog’s 
initialization module; 

© CPINIT-OBJ—Turbo C’s initial- 
ization module to handle 
memory management by Turbo 


LISTING 2: PSORT.PRO 


Prolog rules; ee F . 
© PSORT.OBJ—the compiled Mats LRSegRr 
Turbo Prolog module; _ DATABASE 
® CSORT.OBJ—the compiled db( integer) 
Turbo C module; 
© PSORTSYM—the symbol table aor Me aiacald waits 
created when compiling the sortlist(list,list) - (i,0) language c 
Hoe ee : search(list,integer) - (i,i) language c 
e -LIB—the Turbo 
Prolog Runtime Library; and PREDICATES 
® CL.LIB—the Turbo C Large phe 
del lib repeat 
memory moael Mbrary. test_input(integer) 
Your command line to TLINK find(list, integer) 
should look something like this: poe 
TLINK INIT CPINIT PSORT CSORT cpinit, 
PSORT.SYM, SORT, , PROLOG+CL mans 
By oe bie ee ioe tre CLAUSES 
note about linking this type o ee /* Get items. */ 
project—we can’t use Turbo clearwindow, 
Prolog’s project facility (in the repeat, 
Turbo Prolog development envi- cade ay list (-999 to quit): "), 
ee readin é 
ronment) because we must link in test_input(s), 
Turbo C’s Large memory model findall(N,db(N), List), 
library. Turbo Prolog does not yet sortlist(List,L), | /* Call C function to sort list. */ 
let us link in other libraries. makewindow(2,7,7," In Turbo Prolog ",7,10,7,50), 
write(L),nl, 
THE RIGHT TOOLS FOR Be copie lel elabida ge r 
THE JOB write Enter value to search for: "), 
: * readint(SVal),nl, . 
No ee set of fp ale? find(L,SVal), /* Search for element in list */ 
priate for every task at hand. readchar(_), : 
have most of the tools necessary removewindow, clearwindow. 
ciate: on my car, but I poi ag find(L,Sval):- 
ally Ate eee item irom search(L,SVal), /* If search fails, backtrack to next clause */ 
my neighbor's toolbox. write(Sval," found in List"). 
Likewise, Turbo Prolog is a find(_,SVAL):- 
powerful tool that opens the door write(Sval," NOT found in List"). 
to a wide variety of programming test_input(S):- 
tasks. On occasion, however, I = -999. /* End of list, so succeed & process. */ 
also reach into my collection of test_input(S):- /* If list hasn't been terminated, 
procedural tools. Together, this assert new member, and fail to force 
blend of procedural and declara- 4 aeciges backtracking. */ 
tive programming tools make up assert (db(S)), fatl. 
a toolbox whose creative possi- 
bilities are unequaled by either repeat. 


language alone. @ repeat:- repeat. 


Listings may be downloaded from 
CompuServe as PCSORT.ARC. 
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wo issues back, we added a wildcard 
expansion routine, expwild, to the Run- 
time. While from time to time you may 
want to add other routines, you may find 
that you also want to change existing ones. Chang- 
ing an existing routine, however, can be much 
harder than adding a new one. This time around 
we'll demonstrate how to modify a Runtime routine 
by adding a new capability to an existing major func- 
tion—printf. 
printf is a familiar built-in function that produces 
formatted output, and requires two sets of argu- 
ments. The first set is a single quoted string that con- 
tains a series of literal constants and special format- 
ting instructions. These formatting instructions 
typically consist of a percent sign (%) followed by a 
single letter, such as %d for an integer number. The 
second set of arguments contains the variables and 
constants to be formatted. printf matches each of 
these to a formatting instruction. Consider the printf 
statement: 
4d, 4d.\n", i, j 5 
This statement outputs the characters up to the first 
format instruction (%d) as a literal string. It then 
applies the first %d to the contents of the integer 
variable i, and the next instruction (%d) to the con- 
tents of the integer variable j. It also prints the 
comma and spaces as literals. 
Ifiis 1 andj is 2, this printf statement produces 
the following line: 


printf( "This is a sample: 


This is a sample: 1, 2. 


ADDING A DATE FORMAT TO printf 


The new capability that we'll add to printf is %m, a 
formatting instruction for dates. We chose a simple 
format that consists of a three-letter month abbrevia- 
tion, a space, a two-digit day, a comma and space, 
and then a four-digit year. For example, the date 
6/1/88 appears as “Jun 1, 1988.” Because the date 
structure used by the Turbo C getdate routine 
returns a date that fits in a long, we made our %m 
format instruction require a long argument. 

Listing 1 shows a sample printf that uses %m. The 
only unusual thing about this routine is the bit of 
type casting trickery that we went through to pass the 
contents of the date structure to printf as a long. 
Because C will not allow us to directly cast the date 
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structure as a long, we start with the address of the 
structure, which is a pointer, and cast it as a pointer 
to a long. Then we get the long value addressed by 
that pointer. 

By processing the date as a long, you can easily 
convert other dates to a format that our new printf 
will handle. You can also modify our new printf to 
work directly on the date structure. The DOS date 
function returns its values in two registers—the year 
is returned in one register, and the day and month 
are returned in the other. While you could change 
our code so that %m handles two arguments, each 
printf format directive traditionally matches one 
argument; we chose to follow that tradition. 

Now that we’ve discussed how to use %m, let’s look 
at the way it works. The source code for printf is in 
the file PRINTF.C in the CLIB subdirectory of the 
Runtime source directory structure that we set up in 
our first column (see “Tales From the Runtime,” 
TURBO TECHNIX, November/December, 1987). So 
far, so good: PRINTF.C is even written in C. Look 
closer, however, and you'll find that PRINTF.C is a 
326-byte shell that calls the function _vprinter (see 
Listing 2). If you snoop around the C language a bit, 
you'll find that printf is actually a family of three 
functions, which differ only with respect to where 
they send their output. printf writes to the standard 
output device, while fprintf sends output to a file, 
and sprintf puts its results into a string. All three 
functions use _vprinter for the real work. This 
design keeps all three printf versions consistent, and 
makes our job easier—when we change _vprinter, 
we’re adding the %m function to all three printf 
functions. 


INSIDE _vprinter 
The source for _vprinter is located in the file 
VPRINTER.CAS, which contains 38K of primarily 
assembler code. Since VPRINTER is a .CAS file, it 
has the advantage of containing both C and assem- 
bler code. Because this is a C column, and because 
we prefer C to assembler, we wrote nearly all of our 
_vprinter changes in C. 

In order to change _vprinter, you first need to 
understand how it works; that makes a dip into 
assembler unavoidable. The commented C code in 


VPRINTER, however, explains the routine’s structure 
nicely. We discuss some of the more interesting 
aspects here. 

-vprinter begins with a few important compiler 
directives. The #pragma inline directive enables the 
use of inline assembly language and allows us to 
freely mix C and assembler. _vprinter also contains 
three #include statements. The first include file, 
asmrules.h, contains many macros that are very use- 
ful for inline assembler. The second file, rules.h, 
contains a number of general Runtime declarations. 
The final include file, _printf-h, provides the declara- 
tions of several support routines used by the printf 
family. 

Because _vprinter is designed to support three 
functions that handle output in different ways, it has 
an unusual calling sequence. The basic format for a 
call to _vprinter is: 

int pascal _vprinter( putnF *putter, 
void *outP, 
char *formP, 
va_list argP) 

The first unusual aspect of _vprinter is imme- 
diately apparent—_vprinter uses the Pascal calling 
conventions. Many internal Runtime routines use 
these calling conventions rather than the C rules, 
because the C calling sequence rules are built to 
handle a variable number of arguments. Routines 
that obey these sequence rules push parameters on 
the stack in right-to-left order, and then push the 
return address. The called routine must know how 
many arguments it needs, and be able to get those 
arguments from the stack as it needs them. In addi- 
tion, the called routine cannot clean up the stack; 
the calling routine must clean up the stack after it 
regains control. Routines that obey the Pascal calling 
rules also push the arguments first and then the 
return address, but they push the arguments in left- 
to-right order. Because Pascal does not allow a vari- 
able number of arguments, the called routine cleans 
up the stack as it returns. 

_vprinter follows the Pascal calling conventions 
and accepts a fixed number of arguments; in this 
case, it accepts four. The first argument, putter, is a 
pointer to a function to which putter passes the out- 
put string. This function prints output in the manner 
appropriate to the particular printf family member 
that makes this call. For example, both printf and 
fprintf use the function _fputn to write bytes to a file. 
The second argument, outP, is used by the first argu- 
ment; _vprinter passes outP to the function putter. 
For printf and fprintf, outP is a file pointer for the 
file to which _fputn writes (printf places stdout in 
the address pointed to by outP). 

The last two parameters contain the business part 
of _vprinter’s input. formP is a pointer to the format 
string, which is the first major parameter to printf. 
-Vprinter parses this string and uses the string’s 
directives to format the output. argP is a pointer to a 
list of the rest of the arguments; _vprinter retrieves 
each of these arguments in turn to match directives 
in the format string. 

The basic operation of _vprinter is fairly simple. 
_vprinter reads the format string and outputs the 
literals it finds there until it encounters either a \ or 
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LISTING 1: DATE.C 


/* DATE.C -- routine to test our %m addition to printf. */ 


#include <stdio.h> 
#include <dos.h> 


main() 
€ 


struct date test; /* the structure needed by getdate */ 


getdate( &test ); /* pass it the address of that structure */ 


/* so that it can change that structure */ 
/* Our printf enhancement expects a long. Cast the address */ 
/* of the structure as a pointer to a long, and then get that */ 
/* long. You have to go through this silliness because you */ 
/* cannot directly cast a structure as a long. e/ 


printf( "%n Xs\n", * (long *) &test, "-- everything works!" ); 


LISTING 2: PRINTF.C 
/* the printf family last modified :- 18 Mar 87 
Turbo C Runtime Library version 2.0 


Copyright (c) 1987 by Borland International Inc., All Rights Reserved.| 
*f 


#include <stdio.h> 

#include <_stdio.h> 

#include <_printf.h> 

edecl printf(char *fmt, ...) 
€ 


return _vprinter (_fputn, stdout, fmt, _va_ptr); 


LISTING 3: VPRINTER.CAS 


I te vprinter last modified :- 18 Mar 87 


Turbo C Runtime Library version 2.0 


Copyright (c) 1987 by Borland International Inc., All Rights Reserved.| 
* 
/ 


#pragma inline 
#include <asmrules.h> 
#include <rules.h> 
#include <_printf.h> 
static char WullStringf] = "(null)"; 
static char hexDigits [16] = 


OF Th 28 te ta te, 6h 7 86 tot, At Be tC! (De Et Ee, 
DH 
/**** Begin addition ****/ 


/* Array of month names */ 


static char *months [12] = ¢ 
"Jan", “Feb", "Mar", "Apr", "May", "Jun", 
*Jul", "Aug", "Sep", "Oct", “Wov", "Dec" 
% 


/**** End addition ****/ 
static void 


/* 
Convert 16 bit parameter to 4 hex digits at ES: [di]. 


mear pascal Hex4 (unsigned datum) 


Note: TC does not realize that "scasb" implies DI, so DI is not 
pushed/popped. That is nice, but one day it may cease to 
be true... 
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datun 
asm mov cx, OFO4h 
bx, offset hexDigits 


dh 
cl 


return; 


/* 
_vprinter is a table-driven design, for speed and flexibility. 
There are two tables. The first table classifies all 7-bit ASCII 
chars and then the second table is the switch table which points to 
the function blocks which handle the various classes of characters. 
All characters with the 8th bit set are currently classed as 
don't cares, which is the class of character also used for normal 
alphabetics. All characters less than ' ' (0x20) are also classed 
as don't cares. 
f 


typedef enum 
€ 
si, /* sign fill ('+" or ' *) */ 
_af, /* alternate form */ 
ar, /* format (width or precision) by argument */ 
i. /* left justify */ 


precision 


fill zeros 


_de, 7* decimal */ 
oc, /* octal | */ 
_un, /* unsigned decimal t/ 
_he, /* hexadecimal sy, 
_pt, /* pointer it f 
Btls /* float sad / 
ach, /* char */ 
st, /* string */ 
_ns, /* number sent sal f 
Sez; /* terminator SF | 
de, /* dont care df 
Pe, /* percent ay 
_ne, /* near pointer */ 

fa, /* far pointer * 


dt, /**** Date format ****/ 


2 
characterClass; 


/* Here is the table of classes, indexed by character. 
oh 

static ord8 printCtype [96] = 

« 

fees vily oe URS a VE SG ct LES re Te Rh 
_Si,_de,_de,_af, de, _pe,_de,_de,_de,_de,_ar,_si,_de,_\j,_pr,_de, 


fOOs FS eK OR SF, Be 8 is) se ey OY 
_fz,_nu,_nu,_nu,_nu,_nu,_nu,_nu,_nu,_nu,_de,_de,_de,_de,_de,_de, 
/**** Change the _de (don't care) for M to dt (date) ****/ 

fo Be Ei AGrate (EF GR td KS a Ue Oy 
“de,_de,_de,_de, de, fl, fa, _fl,_sh, de, de, _de,_de,_dt,_ne,‘de, 


fie se RP SE Te I A ee PE Ne OR Ry 
de, _de,_de, de, _de,_de, de, _de,_he,_de,_de, _de,_de,_de,_de,_de, 
/**** Change the _de (don't care) for m to dt (date) ****/ 

fee) ca, (bie dite Fg, Oh ia OE ie a 2 Be ON 
_de,_de,_de,_ch, de, fl,_fl,_fl,_sh,_de,_de, de, _lo,_dt,_ns,_oc, 


7p. ie) , @ OE 1 Ne ev! et ie “SEE O87 
_pt,_de,_de,_st,_de,_un,_de,_de,_he,_dce,_de,_de,_de, _de, de, _de, 
ij 
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FROM THE RUNTIME 
continued from page 141 


a %. If _vprinter finds a \, it gets the next character 
and handles the escape sequence. 

The real work starts when _vprinter encounters a 
%, which indicates a format directive. _vprinter gets 
the type of the format directive and cases off that 
type into code that handles the directive. If _vprinter 
encounters an illegal format character, it abandons 
the format process and then prints the illegal format 
character, along with the rest of the format directive 
string, as literals. _vprinter follows this approach 
because it assumes that the format string and the 
subsequent arguments are not synchronized and can 
no longer be processed together. 


ADDING THE FORMAT DIRECTIVE 


To support our modification of _vprinter with a new 
format directive case, we’ve made several other, 
smaller changes. Listing 3 contains the source for 
the modified _vprinter routine; our changes are 
marked with comments that begin with /**** and 
end with ****/, 

The first new code in _vprinter is a set of month 
names, in the form of a static array of three-char- 
acter entries. We index into this array by using the 
month number minus | to find the name of the 
month we want. While all of our month names are 
the same length, the code handles names of differ- 
ent lengths, so you can also use full month names. 

-vprinter represents a format directive as an enu- 
merated data type containing both directives 
(typedef enum characterClass) and a lookup array of 
characters (printCtype). printCtype maps the actual 
format characters (such as d, s, f, and now m) to 
their corresponding internal directive cases 
(_de, _st, _fl, and now _dt, respectively). We changed 
both characterClass and printCtype to handle a new 
case for our date format, _dt, and added this new 
case to the end of the enumerated data type. We 
added entries for both lowercase and uppercase m 
into the character array printCtype. To support the 
_dt case, we also declared five new variables. Three 
of these variables—year, month, and day—are inte- 
gers that hold the parts of a date. We also declared a 
character pointer to temporarily hold the month 
string, and another character pointer for the output 
string. 

Before we get into our new code, we should men- 
tion something odd that happened as we worked on 
-vprinter. Our new code somehow caused a prob- 
lem with some code (_si) in another part of the pro- 
gram. _si, which is the case that handles a sign 
directive, contains a short jump (limited to 128K) to 
vpr_nextSwitch. Since our new code doesn’t fall 
between the jump and the destination, it should not 
have affected this jump; nevertheless, the short jump 
broke, probably due to the different alignment of the 
code. This break caused the assembly language code 
passed by Turbo C to MASM to generate a MASM 
error. The fix was easy: we turned the jump into a 
normal jump by removing short from it. If you make 
our other changes, be sure to make this one. 
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int pascal _vprinter (putnF *putter, 
void *outP, 
char *form, 
va_list argP 


€ 


/* 
The list of arguments *argP is combined with literal text in the 
format string *form according to format specifications inside 
the format string. 

The supplied procedure “putter is used to generate the output. 
It is required to take the string S, which has been constructed by 
_vprinter, and copy it to the destination outP. The destination may 
be a string, a FILE, or whatever other class of construct the caller 
requires. It is possible for several calls to be made to *putter 
since the buffer S is of limited size. 


*putter is required to preserve SI, DI. 


The only purpose of the outP argument is to be passed through to 
putter. 

The object at *argP is a record of unknown structure, which 
structure is interpreted with the aid of the format string. Each 
field of the structure may be an integer, long, double, or string 
(char *). Chars may appear but occupy integer-sized cells. Floats, 
character arrays, and structures may not appear. 

The result of the function is a count of the characters sent 
to *outP. 

There is no error indication. When an incorrect conversion spec 
is encountered _vprinter copies the format as a literal (since it is 
assumed that alignment with the argument list has been lost), 
beginning with the '%' which introduced the bad format. 

If the destination outP is of limited size, for example a string 
or a full disk, _vprinter does not know. Overflowing the destination 
causes undefined results. In some cases *putter is able to handle 
overflows safely, but that is not the concern of _vprinter. 


The syntax of the format string is: 
format ::= ({literal] ['%' conversion ])* ; 
conversion ::= '%' | [flag]* [width] ['.' precision] ['l'] type ; 
fleg ese f=9 fj eee | ore | tae | Ot s 
width z:= '*' | number ; 
precision ::= '.' ('*" | number) ; 


type ::= 'd']'7']to furfixt int | xe] 
ft) tetlres *g'|'G'| 
1 


tc! 's 
'p! Nr ‘ft 
*/ 
# «define Ssize 80 
typedef enum 
€ 
flagStage, fillzStage, wideStage, dotStage, precStage, 
ellStage, typeStage, 
%) 
syntaxStages; 
typedef enum 
€ 
altFormatBit = 1, /* the '#' flag iff 
leftJustBit = 2, /* the '-' flag Ld J 
notZeroBit = 4, /* 0 (octal) or Ox (hex) prefix */ 
fillZerosBit = 8, /* zero fill width wy 
isLongBit = 16, /* long-type argument */ 
farPtrBit = 32, /* far pointers / 
altOxBit = 64, /* '#' flag confirmed for %x format */ 
> 
flagBits; 
ordi6—aP; 
char fc; /* format char, from the format string */ 
char isSigned; /* chooses between signed and unsigned 
ints */ 
int!6 width; 
intl6 precision; 
bits8 flagSet; 
char plusSign; 
int leadz; 
ordi6 = abandonP; /* posn of bad syntax in format 
string */ 
char tempStr [38]; /* longest _realcvt string */ 
cardié totalSent = 0; /* characters sent to putter */ 
card8 Scount = Ssize; /* free space remaining in S$ */ 
char S$ [(Ssize]; /* temporary constructed result 
buffer */ 
register SI, DI; /* prevent the compiler making its 
own usage */ 
int year, month, day; /**** Holders for the parts of a 
date eneny 


char *cP; 
char *monthptr; 


/**** Pointer to output string ****/ 
/**** Temporary pointer ****/ 


/* the remaining variables are held entirely in registers 
char hexCase; /* choose upper or lower case Hex 
alphabet */ 

long templ; 

syntaxStages stage; -- CH 

char CH 

char cP; 

int *iP; 
#endi f 


/* General outline of the method: 


First the string is scanned, and conversion specifications detected. 
The preliminary fields of a conversion (flags, width, precision, 
long) are detected and noted. 

The argument is fetched and converted, under the optional 
guidance of the values of the preliminary fields. With the sole 
exception of the 's' conversion, the converted strings are first 
placed in the tempStr buffer. 

The contents of the tempStr (or the argument string for 's') 
are copied to the output, following the guidance of the preliminary 
fields in matters such as zero fill, field width, and justification. 
if 


#if 0 

/* Warning: the following C code is comment only ! It has not 
been tested. 

ot 


define PutToS(c) \ 
(SfaP++] = ¢; \ 
if (--Scount == 0) \ 
{ S{aP] = 0; putter (S, Ssize, outP); = 0;\ 
totalSent += (Scount = Ssize); } ) 


VPNEXT = 
if ('\O' == (fc = *(formP++))) /* the normal end */ 
{ 
if (Ssize - Scount) 
€ 
totalSent += (Ssize - Scount); 
putter (S, Ssize - Scount, outP); 
> 
return totalSent; 
> 


if (C'X! == fc) && (1X! I= (fc = *(formP++)))) goto vpCONV; 


PutToS (fc); 
goto vpNEXT; 


vpCONV: 
abandonP = (unsigned) forme; 
width = -1; 
precision = -1; 
plusSign = '\0'; 
leadz = 0; 
#if LDATA 
flagSet = farPtrBit; 
#else 
flagSet = 0; 
#endi f 
stage = flagStage; 
cP = 1+tempStr; 
goto vp0oSwitch; 


/*tempStr [0] may be used for inserting 


vpNextSwitch: 
fe = *(form++); 
vpDoSwitch; 
if (fe < ' ') || (fe & 0x80)) goto vpabanton; 
switch (printCtype [fc-' ']) 
€ 
/* alterneteForm */ 


case (_af): 
if (stage > flagStage) goto vpAbandon; 
flagBits |= altFormatBit; 
goto vpNextSwitch; 


case (_lj): /* leftJust */ 
if (stage > flagStage) goto vpAbandon; 
flagBits |= leftuustBit; 
goto vpNextSwitch; 

case (_si): /* sign fill */ 
if (stage > flagStage) goto vpAbardon; 
if (plusSign != '+') plusSign = fc; 
goto vpNextSwitch; 


case (_ne): /* near pointer */ 
if (stage > flagStage) goto vpAbandon; 
flagBits &= “farPtrBit; 
goto vpNextSwitch; 

case (_fa): /* far pointer */ 
if (stage > flagStage) goto vpAbandon; 
flagBits |= farPtrBit; 
goto vpNextSwitch; 
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case (_ar): /* format by arg */ 
temp = *((Cint *) argP)++); 
if (stage < wideStage) 
€ 


width = temp; stage = wideStage + 1; 


else 
if (stage == precStage) 
€ 
precision = temp; stage ++; 
> 
else 
goto vpAbandon; 
goto vpNextSwitch; 


case (_fz): /* fillZeros */ 
if (stage > flagStage) goto vpr_NUMERAL; 
if (flagBits & leftJustBit) 
goto vpNextSwitch; /* 1B 12.may.87 */ 
flagSet |= fillZerosBit; 
stage = fillzStage; 
goto vpNextSwitch; 


case (_pr): /* precision '.' */ 
if (stage >= precStage) goto vpAbandon; 
stage = precStage; 
goto vpNextSwitch; 


case (_nu) /* mumeral */ 
vpr_NUMERAL : 
if (stage <= wideStage) 
{ width = (width < 0) ? fe - 'O' : width*10+(fc - '0'); 
stage = wideStage; 


else 
if (stage != precStage) 
{ 
precision = precision * 10 + (fe - '0'); 
stage = precStage; 
> 
else 
goto vpAbandon; 
goto vpNextSwitch; 


case (_lo): /* long */ 
flagSet l= isLongBit; stage = ellStage; 
goto vpNextSwitch; 


case (_sh): /* short*/ 
flagSet &= “isLongBit; stage = ellStage; 
goto vpNextSwitch; 


case : radix = 10; goto vpINT; 
case : radix = 8; goto vpuINT; 
case : radix = 10; goto vpuiNT; 
case : hexCase = fc - ('x' - 'a'); 

radix = 16; goto vpuINT; 
case : goto vpFLOAT; 


cP = (char *) ((Cint *) argP)++); cP [1] = 0; goto vpcory; 
case (_st) : 
cP = *(((char **) argP)++); goto vpCOPY; 


case (_ns) : /* number sent */ 
iP = *((Cint *) argP)++); 
*iP = totalSent + Ssize - Scount; 
goto vpNEXT; 


case ( pt) : goto vpPointer 


case (zz) : 

case (_pc) : 

case (_dc) : goto vpAbandon; 
> 


VpUINT: 
isSigned = false; 
tempL = (flagSet & isLongBit) ? *(((long *)argP)++): 
*(((unsigned *) argP)++); 
goto vpPUTINT; 


vpINT: 
isSigned = true; 
tempL = (flagSet & isLongBit) ? *(((long *) argP)++) : 
*((Cint *) argP)++); 
VpPUTINT: 
notZero = tempt != OL; 
cP = 1 + tempStr; /* tempStr [0] reserved for sign */ 
_longtoa (templ, cP, radix, isSigned, hexCase); 
if (precision > 0) 
€ 


if (precision > (len = strlen (cP) - ("cP == '-')) 
leadZ = precision - len; 
else 
precision = len; /* ragged format is safer than lost 
digits */ 
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FROM THE RUNTIME 
continued from page 142 


We've added the new case _dt after the last exist- 
ing case that did any real work. We comment the 
code heavily, but a few points deserve further 
explanation. 

We save the current position in the format string, 
and the format character itself, in the variables 
formP and fc (respectively), because the rest of the 
_vprinter cases save them. We’ve used assembler 
code because the values were already in registers, 
and assembler provides the quickest way to access 
these values. 

The next block of code takes the long argument 
from argP that contains the date, and unpacks that 
date into the year, day, and month variables. The 
first word contains year; although DOS says that 
dates start from 1980, the year is actually counted 
from zero so we don’t need to convert it. We extract 
the year with a bit of casting trickery: First, we cast 
the argP pointer to an integer pointer so that we can 
access the integer year. Next, we get the value of 
year, and then increment the pointer argP. Notice 
that we increment argP only after we have cast it as 
an integer, so that argP is incremented correctly by 
two bytes. We use similar tricks to retrieve the day 
and month, but because they are one byte each, we 
get them as characters and then cast them to inte- 
gers. The final cast is unnecessary because C would 
do the conversion for us automatically, but we do it 
explicitly to make the intent of the code clear. 

We then set our string pointer to the work area 
pointer, tempStr, that is used by the rest of the code 
in _vprinter. 

From here on, our code is a fairly typical number- 
to-character conversion exercise. We index into our 
month array to find the month name and move that 
name, along with a trailing space, into the work 
string. We then convert the day to a character string 
and add the string, a comma, and a space to the 
work string. Finally, we convert the year to a charac- 
ter string and add it to our work string. 

The only unusual code here involves the function 
_longtoa. This function, as its name implies, trans- 
lates a long into an ASCII string. Its source code 
is in the file LTOA.CAS in the CLIB subdirectory. 
_longtoa requires five arguments. The first two argu- 
ments—the number to be translated and the destina- 
tion string—are the main ones. The third parameter 
specifies the radix (_longtoa handles any radix from 
2 to 36). The final two arguments specify how the 
sign should be handled and whether to capitalize let- 
ters if the output is hexadecimal; since we don’t need 
either of them here, we set them both to zero. Be- 
cause _longtoa does not update the destination 
string pointer to point to the end of the result, we 
handle that step manually after converting the day. 

The last bit of our code is in assembler so that we 
can easily jump to the code labeled vpr_COPY, 
which is used by all of the _vprinter cases to handle 
the final output and cleanup. Our code places a 
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> asm cmp al, '%' /* The '%' character begins a 
goto vpNUMERIC; conversion */ 
asm je vpr_CONV 
vpPointer: vpr_literal: /* but "4" is just a literal 'X'. */ 
isSigned = false; asm mov SS_ [di], al 
cP = tempStr; asm inc di 
asm dec BYO (Scount) 
tempL = *(((unsigned *) argP)++); asm ig vpr_nextCh 
if (flagSet & farPtrBit) _SimLocalCall_ 
€ imp vpr_CallPutter 
Hex4 (cP, *((Cunsigned *) argP)++); jmp short vpr_nextCh 
cP += 4; 
*(cPt+) = 's'2 
> vpr_respondJmp: 
Hex4 (cP, templ); asm jmp vpr_respond 
tempL = (flagSet & farPtrBit) 7? *(((long *) argP)++) : 
*((Cunsigned *) argP)++); 
/* lf arrived here then a conversion specification has been 
notZero = false; /* suppress check for 0/0x/0X prefixing */ encountered. */ 
*(cP += 4) = '\0'; 
len = cP - tempStr; vpr_CONV: 
cP = tempStr; asm mov abandonP, si /* abandon will print from here */ 
precision = MAX (len, precision); 
goto vpCoPY; asm lods BYO (ES_ [si]) 
asm cmp al, '%! 
VpFLOAT: asm je vpr_literal 
cP = 1 + tempStr; /* tempStr [0] reserved for sign */ 
_frealcvt (((double *) argP)++, aP, di /* keep the result pointer safe. */ 
(precision > 0) ? precision : 6, 
cP, fc, altFormat); Cx tk /* CH is flagStage */ 
notZero = false; /* suppress check for 0/0x/0X prefixing */ leadz2, cx 
goto vpCOPY; 
BYO (flagSet), farPtrBit 
VpNUMERIC: 
if (plusSign && (*cP != '-'))  *(--cP) = plusSign; flagSet, cl 


vpCOPY : plusSign, cl 
len = strlen (cP); WO (width), -1 
if CaltFormat & notZero) WO (precision), -1 
€ j short vpr_doSwitch 
if ((fe == 'o') && (leadZ <= 0)) leadZ = 1; 
if ((fe == 'x') || (fe == 'X')) vpr_nextSwitch: /* loop to here when scanning flags */ 
€ asm lods BYO (ES_ [si]) 


flagSet |= altOxbit; 
width -= 2; vpr_doSwitch: /* this is the major switch. */ 

if (CleadzZ -= 2) < 0) J* DM : 05/11/87 */ ea) ees 
leadz = 0; /* DM : 05/11/87 */ asm mov /* save original char in DL */ 

> asm xchg 


> asm sub 
if (! leftJust) cmp 


while (width > (len + leadZ)) jae 


t mov 
width --; PutToS (' '); switch (BX) /* ===> clobbers AX, BX <=== */ 
> 


if (flagSet & altOxBit) 


vpr_jmpAbandon: /* Extend local jump range */ 
PutToS ('0'); PutToS (fc); asm jmp vpr_abandon 


> 
if (leadz > 0) 
€ case (_af): /* when '#' was seen */ 
len -= leadz; asm cmp ch, flagStage 
width -= leadz; asm ja vpr_jmpAbandon 
if (Cc = cP*) == '-") || Co == 4 ') || (Cc == t+") asm or BYO (flagSet), altFormatBit 
if (len > 0) € width--; len --; PutToS (*(cP++)); > asm jmp short vpr_nextSwitch 
while (leadZ-- > 0) PutToS ('0'); 
> case (_lj): /* when '-' was seen */ 
width -= len; asm cmp ch, flagStage 
while (len -- > 0) PutToS (*(cP++)); asm ja vpr_jmpAbandon 
if (leftJust) asm or BYO (flagSet), leftJustBit 
while (width-- > 0) PutToS (' '); asm jmp short vpr_nextSwitch 
goto vpNEXT; 
case (_si): /* when ' ' or '+' was seen */ 
#endi f asm cmp ch, flagStage 
asm ja vpr_jmpAbandon 
asm cmp BYO (plusSign), 2Bh /* ‘+! */ 
asm je vpr_nextSwitch /* * * ignored if '+' already */ 
asm mov plusSign, dl 
asm asm imp vpr_nextSwitch /**** Eliminate the short ****/ 


asm i case (_ne): /* near pointer */ 
asm asm cmp ch, flagStage 
asm ja vpr_abandonJmp 
/* This paragraph is arranged to give in-line flow to the most asm and BYO (flagSet), NOT farPtrBit 
frequent case, literal transcription from *formP to *outP. */ asm jmp vpr_nextSwitch 


vpr_NEXTap: case (_fa): /* far pointer */ 
asm mov di, aP asm cmp ch, flagStage 

vpr_NEXT: /* loop to here when DI still valid */ asm ja vpr_abandonJmp 

asm LEs_ si, form asm or BYO (flagSet), farPtrBit 


asm jmp vpr_nextSwitch 
vpr_nextCh: /* resume here from this literal/ 


Space scan section */ 

asm lods BYO (ES_ [si}) case (_ fz): /* leading width '0' acts as a flag */ 

asm or al, al asm cmp ch, flagStage 

asm jz vpr_respondJmp asm ja case_nu /* else it is just a digit */ 
asm test BYO (flagSet), leftJustBit /* TB 12.may.87 */ 
asm jnz short  vpr_nextSwitchJmp /* TB 12.may.87 */ 
asm or BYO (flagSet), fillZerosBit 
asm mov ch, fillzStage /* but it must be part of 

width */ 

asm jmp short vpr_nextSwitchJmp 
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vpr_abandonJmp: 
asm imp 


/* Extend local jump range */ 


vpr_abandon 


case (_ar): /* when '*' was seen */ 
#if LDATA 


Es 


di, argP 
ax, ES_ [di] /* it causes the next argument */ 
add WO (argP), 2 Piss to be taken, */ 


ch, wideStage 
vpr_argPrec 


depending on the stage, */ 


width, ax 
asm mov ch, wideStage + 1 
vpr_nextSwitchJmp: 

asm jmp vpr_nextSwitch 


as the width, */ 


vpr_argPrec: 


asm cmp ch, precStage 


asm jne vpr_abandonJmp 
asm mov precision, ax /* or as the precision. */ 
asm inc ch 

jmp short vpr_nextSwitchJmp 


/* when '.' is seen */ 
ch, precStage 
vpr_abandonJmp 
ch, precStage /* @ precision should follow */ 


short  vpr_nextSwitchJmp 


/* When a numeral is seen, it may be either part of a width, or */ 
/* part of the precision, depending on the stage. */ 

case (_nu): /* when 0..9 seen */ 
case_nu: 

/* move char back into AL */ 


ch, wideStage 
vpr_precNumeral 


ch, wideStage 
ax, width 

ax, ax 
vpr_nextSwitchJmp 
asm mov dx, 10 

asm mul dx 

width, ax 

short vpr_nextSwitchJmp 


/* is this the first width digit ? */ 
/* default width was -1 */ 


vpr_precNumeral : 
asm cmp 
asm jne 


ch, precStage 
vpr_abandonJmp 


asm xchg ax, precision 

asm or ax, ax /* is this the first precision digit ? */ 
asm jl vpr_nextSwitchJmp /* default precision was -1 */ 
asm mov dx, 10 

asm ml dx 


asm add 
asm jmp 


precision, ax 

vpr_nextSwi tchJmp 

case (_lo): Yh was seen */ 
asm or BYO (flagSet), islongBit 

asm mov ch, ellStage 

asm jmp vpr_nextSwitchJmp 


/* if 'h' was seen */ 
BYO (flagSet), not isLongBit 
ch, ellStage 
vpr_nextSwi tchJmp 


case (_sh): 
asm and 
asm mov 


asm jmp 
/* The previous cases covered all the possible flags. Now the 
following cases deal with the different argument types. 
The first group of cases is for the integer conversions. */ 


*/ 


case (_0c): /* octal 
asm mov 


asm jmp 


bh, 8 


short vpr_NoSign 


case (_un): /* unsigned 
asm mov bh, 10 
asm jmp short  vpr_UINT 


case (_he): /* hex 
asm mov bh, 10h 

asm mov BU Ae = txt 

asm add bl, dl 

vpr_NoSign: 

asm mov BYO (plusSign), 0 

/* jmp short vpr_UINT LF 


146 TURBO TECHNIX May/June 1988 


vpr_toAscii: 


asm 
asm 
asm 
asm 
asm 


vpr_shortInt: 


ine 
ine 


mov 


je 

mov 
inc 
inc 


#if LDATA 


asm 
#endi f 
asm 


imp 


BYO (isSigned), false 
fc, dl /* remember the type character. */ 


di, argP 


/* fetch the argument.w0 */ 
/* zero extend by default */ 


ax, ES_ [di] 
dx, dx 


short vpr_toAscii 


/* decimal ah 
bh, 10 


BYO (isSigned), true 
fe, dl /* remember the type character. */ 


di, argP 
ax, ES_ [di] 


fetch the argument.w0 */ 
sign-extend by default */ 


di 

di /* advance past arg.w0 */ 
form, si /* remember progress through format */ 
BYO (flagSet), isLongBit 
vpr_shortInt 

dx, ES_ [di] 

di 

di 


/* short or long int ? */ 


argP, di 

da& 

ax /* (temp */ 
ax, dx 

vpr_doLtoA 

BYO (flagSet), notZeroBit 


ss 
di, tempStr [1] 


di tial 
al, bh 


, cP == I+tempStr */ 


ax /* AL == 
al, isSigned 
ax hig « isSigned */ 


bx /* BL == , hexCase) */ 
EXTPROC (_longtoa) /* returns pointer to string */ 


» radix */ 


ES /* ES_ [di] = cP == 1+tempstr */ 
/* ES is needed in all models */ 


dx, precision 

dx, dx 
vpr_countActual Jmp 
vpr_testFillZeros 


vpr_countActual Jmp: 


* 


imp 


vpr_countActual 


The 'p' conversion takes either a near or a far pointer and puts 
it out in the usual Intel xxxx:xxxx hex style. 


ae 


case (_pt): 


asm 


/* pointer «/ 

/* remember the type character. */ 

/* remember progress through 
format */ 


fc, dl 
form, si 


di, tempStr 


bx, argP 
ES_ [bx] 
bx 
bx 
argP, bx 


/* fetch the argument.w0 */ 


BYO (flagSet), farPtrBit 
vpr_ptrLsw 


ES_ [bx] /* fetch the argument.wi */ 


/* add di, 4 Hex4 does this 


asm mov 
asm stosb 


ety ts 


vpr_ptrLSw: 

asm push ss 
asm pop Es 
asm call Hex4 


f= di, 4 
BYO (SS_ {dil}, 0 


Hex4 does this 


BYO (isSigned), false 
(flagSet), NOT motZeroBit 


/* CX = len, DI = tempStr Ff 


precision 
dx, cx 
vpr_ptrEnd 
dx, cx 


vpr_ptrEnd: 


asm jmp vpr_testFillZeros 


/* The 'c' conversion takes a character as parameter. However, note 
that the character occupies an (int) sized cell in the argument 
list. */ 


case (_ch): char */ 
mov i remember progress through format */ 
remember the type character */ 


di, tempStr [1] 
h, 0 


/* terminate the temporary string. */ 
vpr_CopyLen 
/* The 's' conversion takes a string (char *) as argument and copies 
the string to the output buffer. */ 
case (_st): 


asm form, si 
asm fc, dl 


/* string wy 
/* remember progress through format */ 
/* remember the type character */ 


asm di, argP 
asm BYO (flagSet), farPtrBit 

asm j vpr_farString 

Hit 

asm j vpr_abandonJmp /*DS can't be assumed in HUGE model*/ 
#else 

asm di, ES_ [di] 
asm WO (argP), 2 
asm 

asm 

asm /*8$*/ 
asm jmp short vpr_countString 
#endi f 

vpr_farString: 

asm l di, ES_ [di] 
asm WO (argP), 4 
asm ax, es 

asm ax, di 


/* [di] = (DS:char *) *(argP++) */ 


/* ES: [di] = (char *) *(argP++) */ 


/*33*/ 
/*$8*/ 


vpr_countString: 

asm j WotaNul (Ptr 

asm os 

asm ES 

asm di,offset NullString 


/*3$*/ 
/*$$*/ 
/*S8*/ 
/*$8*/ 


WotaNul Ptr: 
_SimLocalCalt_ 

asm j vpr_strien 

asm cx, precision 
asm j vpr_CopyLenJmp 
asm cx, precision 
vpr_CopyLenJmp: 
asm imp 


/*$$*/ 


/* CX = strlen (ES: [di]) */ 


/* precision may truncate string. */ 


vpr_Copyten 


/* ALL real-number conversions are done by _realcvt. */ 


/* float if 
/* remember progress through format */ 
/* remember the type character */ 


case (_fl): 
asm mov 
asm mov 


form, si 
fc, dl 


FROM THE RUNTIME 
continued from page 144 


string pointer in ES:DI (the standard place to store a 
string pointer), which points to the output string we 
create. Because tempStr is a local variable, we know 
that it is in our stack segment, so we set ES to SS. (We 
use the trick of pushing SS and then popping the 
contents into ES to get around the fact that Intel 
architectures before the 80386 treat these two regis- 
ters as less than full, and will not let you move from 
SS to ES.) We finish by putting the address of 
tempStr into DI and jumping to vpr_COPY. 

That’s it! All of the printf family members can 
now handle dates. When it comes to working with 
existing routines, the bulk of the effort goes into 
understanding how the code works. Adding the new 
code is simple once you master the original code. 

We've not yet selected the topic for our next 
column, and are considering everything from text 
processing goodies to BIOS-independent screen 
handling code. Do you have any suggestions? Like 
some radio stations, we welcome your requests. Write 
to us care of TURBO TECHNIX, and we'll see what 
we can do. Until then, have fun as you continue to 
work with the Runtime and Turbo C. @ 


Mark L. Van Name is a freelance writer. Bill Catchings is 
a freelance writer and a software engineer at Data General 


Corp. 


Listings may be downloaded from CompuServe as 
PRINTF.ARC. 


TURBO C QUICK C LET'S C DESMET C DATALIGHT C ECO-C 
LATTICE C MICROSOFT C AZTEC C COMPUTER INNOVATIONS C 


NEW --- Limited time offer. 


Peacock System's CBTREE 
Object library for only $49! 


Our FULL COMMERCIAL VERSION of CBTREE in object library format 
is being offered for the amazingly low price of $49. 


CBTREE provides you with easy to use functions that maintain key 
indexes on your data records. These indexes provide you with fast, 
keyed access, using the industry standard B+tree access method. 


Everything you need to fully utilize CBTREE in your applications is 
included. The CBTREE source code can be purchased later at any 
time for the $110 difference. Example source programs and utilities 
are included FREE. 


CBTREE source library $159 
Object library only $49 


This limited time offer is simply too good to refuse. Peacock's standard 
ROYALTY FREE, UNCONDITIONAL MONEY-BACK GUARANTEE, 
AND FREE TECHNICAL SUPPORT applies to this offer. 


To order or for additional information 
call 1-800-346-8038 or (703) 847-1743 or write: 


PEACOCK SYSTEMS, INC. 
2108 GALLOWS ROAD, SUITE C 
\ VIENNA, VA 22180 
PEACOCK SYSTEMS, INC 


Trademarks: Turbo C (Borland); Quick C (Microsoft); Let's C (Mark Williams); DeSmet C (DeSmet 
Software); Datalight (Datalight); Lattice C (Lattice); Microsott C (Microsoft): Aztec C (Manx Sottware); 
Computer Innovations C (Computer Innovations); Eco-C (Ecosott, Inc) 
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asm LES_ di, argP 
asm mov 
asm or Cx, cx 
asin jnt vpr_cvtReal 
asm mov cx, 6 


cx, precision 
/* is precision defaulted ? */ 


vpr_cvtReal: 

#if LDATA 

asm push Es 
tendif 

asm push di 
asm push cx /* 
#if LDATA 


/* (valueP */ 
» ndec */ 


asm -$s 

#endif 

asm bx, tempStr [1] 
asm bx 

asm dx 

asni ax, altFormatBit 
asm al, BYO (flagSet) 
asm ax 

asm EXTPROC (_realcvt) 


ek ok 
, formch */ 


, altFormat) */ 


asm WO (argP), 8 /* ((double *) argP) ++ */ 
asm 
asm 


asm lea di, tempStr [1) 


/* ES_ [di] = cP == 1+tempStr */ 


vpr_testFillZeros: 

asm test BYO (flagSet), fillZerosBit 

asm jz 

asm mov 

asm or 

asm jing 

vpr_countActual : must be well defined! */ 
_SimLocalCall_ 

asm jmp vpr_strlen = strlen (ES: [di]) */ 


asm sub 
asm ing 
asm mov 


dx, cx = leadZ */ 
vpr_NUMERIC 
leadZ, dx 


/* 1f arrived here, then tempStr contains the result of a numeric 
conversion. It may be necessary to prefix the number with a 
mandatory sign or space. */ 


vpr_NUMERIC: 

asm al, plusSign 
asm al, al 

asm j vpr_COPY 
asm BYO (ES: [di]), '-' 
asm vpr_COPY 

asm di 

asm WO (leadz), 1 
asm WO (leadz), 0 
asm Es: [di], al 


/* ES must be well defined ! tf 


/* don't allow negative leadZ */ 
/* *(--cP) = plusSign */ 


/* If arrived here then ES: [di] = cP points to the converted string, 
which must now be padded, aligned, and copied to the output. */ 


vpr_COPY: 
_SimlocalCall_ 
asm jmp vpr_strien 


vpr_CopyLen: 
asm mov 
asm mov 


/* CX = strlen (ES: [di]) */ 


/* comes from %c or %s section */ 
/* cP == ES: [si] */ 


asm width /* BX = width */ 
asm notZeroBit + altFormatBit 

asm BYO (flagSet) ° 

asm notZeroBit + altFormatBit 

asm j vpr_doLead 

asm ah, fc 


asm ah, ‘o! 

asm j vpr_maybeA | thex 
asm WO (leadZ), 0 /* alternate mode with octal format*/ 
asm j vpr_doLead /* requires there to be at least */ 
asm WO (leadZ), 1 /* one leading zero. */ 


asm short vpr_doLlead 


vpr_maybe | thex: 

asm cmp on, ‘x! /* alternate mode with 'x' or 'X! */ 
asm je vpr_isAl tHex /* format requires sending a */ 
asm : Yak "Ox" or "OX" prefix. */ 
asm jne 

vpr_isAl tHex: 

asm or BYO (flagSet), altOxsit 
asm sub bx, 2 

asm sub WO (leadz), 2 leadZ -= 2; */ 
asm jnt vpr_dolead DM : 05/11/87 */ 
asm mov WO (leadz), 0 DM : 05/11/87 */ 


width -= 2; */ 


vpr_doLead: 
asm add cx, leadz /* CX = len + leadzZ */ 
asm test BYO (flagSet), leftJustBit /* is result to be left 
justified? */ 
asm jnz vpr_checkOx 
asm jmp short vpr_nextJust /* (! leftJust) == leftFill */ 
vpr_justLoop: 
asm mov aly (fet 
_SimLocalCalt_ 
asm jmp vpr_PutTos 
asm dec bx 


vpr_nextJust: 
asm cmp 
asm ig 


bx, cx 
vpr_justLoop 


vpr_checkOx: 
asm test 
asm jz 


BYO (flagSet), altOxBit 
vpr_checkLeadz 


asm mov al, ‘0! 
_SimLocalCal t_ 

asm jmp vpr_PutToS 

asm mov al, fe 
_SimLocalCall_ 

asm jmp vpr_PutTos 


vpr_checkLeadZ: 
asm mov 

asm or 

asm ing 


/* is leading zero fill required ? */ 


len -= leadz */ 
width -= leadz */ 


asm sub 
asm sub 


asm eny leading sign must be */ 
asm ; copied before the */ 
asm je leading zeroes. */ 
asm cmp 
asm je 
asm cmp 
asm jne 
vpr_leadSign: 
asm lods BYO (ES: [si]) 
_SimlocalCalt_ 
asm jmp vpr_PutTos 
asm dec cx 
asm dec bx /* anticipates actualCopy */ 


vpr_signedLead: 
asm xchg 
asm jexz 


cx, dx 
vpr_leadDone 


/* leading zeroes follow sign */ 


vpr_leadZero: 

asm mov al, ‘O* 
_SimLocalCallt_ 

asm jmp vpr_PutToS 

asm loop vpr_leadZero 


vpr_leadDone: 


ashi xchg cx, dx 


/* Now we copy the actual converted string from tempStr to output. */ 


vpr_actualCopy: 
asm sub 
asm jexz 


bx, cx 
vpr_copied 


/* width -= len; */ 


vpr_copyLoop: /*this is the high-point of _vprinter!*/ 
asin lods BYO (ES: [si]) 
asm mov BYO (SS_ [di}), al 
asm inc di 
asm dec BYO (Scount) 
asin jg vpr_loopTest 
_SimLocalCall_ 
asm jmp vpr_CallPutter 
vpr_loopTest: 
asm loop vpr_copyLoop 


vpr_copied: 


/* Is the field to be right-filled ? */ 


asm or 
asm jng 
asm mov 
vpr_rightLoop: 
asm mov at, +: 
_SimLocalCalt_ 
asm jmp vpr_PutToS 
asm loop vpr_rightLoop 


bx, bx 
vpr_done 
cx, bx 


/* any remaining width ? */ 
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/*\f arrive here, the conversion has been done and copied to output*/ 
vpr_NEXT 


/* mumber sent */ 


form, si /* remember progress through format */ 


di, argP 

BYO (flagSet), farPtrBit 

vpr_farCount 

vpr_abandonJmp /*DS can't be assumed in HUGE model*/ 


di, ES_ [di) 
WO (argP), 2 
os 


/* [di] = (DS:char *) *(argP++) */ 


ES 

short vpr_makeCount 
#endif 
vpr_farCount: 
asm les 
asm add 


di, ES_ [di] 
WO (argP), 4 


/* ES: [di] = (char *) *(argP++) */ 


vpr_makeCount : 


asm mov ax, Ssize 
asm sub al, Scount 
asm add ax, totalSent 
asm mov Es: [di], ax 
asm jmp vpr_NEXTap 


/**** Begin addition ****/ 
/* Code for date processing */ 
case (_dt) : 


asm mov 
asm mov 


form, si 
fc, dl 


/* Save progress through format */ 
/* Save the type character */ 


/* Unpack the components of the date. Year - int, day - char, 
and month - char. Casting is the key here. */ 


year = *(((int *) argP)++); 
day = (int) *(((char *) argP)++); 
month = (int) *(((char *) argP)++); 


cP = tempStr; /* Get a pointer to the destination */ 


Move the appropriate month name into the destination string. 
Follow it by a space. */ 


monthptr = months [month-1]; 
while ((*cP = *monthptr++) f= '\O') cP++; 
*cp++ =! +; 


_longtoa converts a long into an ASCII string. The first 
argument is the long, the second the destination, the third 
the radix. The remaining two are not used here. Convert 
the day into ASCII. */ 


_longtoa ((long) day, cP, 10, 0, 0); 


_longtoa does not update the string pointer, so we do that by 
hand. Add a comma and a space for the sake of neatness. */ 


cP = tempStr + strlen (tempStr); 
*cP++ = vite 
*cp++ =! as 


Convert the year to ASCII. */ 
_longtoa ((long) year, cP, 10, 0, 0); 


vpr_COPY takes care of all the applying of arguments to 

the string we created (such as maximum length, right 
justification, etc.) and then calls the function to output 
the resulting string. vpr_COPY requires that ES:D1 point 
to the string to process, so we set it up before calling. */ 


asm push SS 

asm pop ES 

asm lea di, tempStr 
asm jmp vpr_COPY 


/**** End addition ****/ 


case (_zz): /* \O characters, unexpected end of format string */ 
case (_de): /* ordinary “don't care" chars in the wrong position */ 
case (_pc): /* '%' percent characters in the wrong position */ 

/* goto vpr_abandon Lh 
> /* end switch */ 


/* If the format goes badly wrong, then copy it literally to the 
output and abandon the conversion. */ 


vpr_abandon: 
asm mov 
#if LDATA 
asm mov 
#endif 

asm mov 
asm mov 


si, abandonP 
Es, Wi (formP) 


di, aP 
al, '%*! 


vpr_abandLoop: 

_SimLocatCall_ 
asm jmp vpr_PutToS 
asm lods BYO (ES_ [si]) 
asm or al, al 
asm jnz vpr_abandl oop 


/* If arrived here then the function has finished (either correctly 
or not). */ 


vpr_respond: 
asm cmp BYO (Scount), Ssize /* anything waiting to be 
written? */ 
asm jnt vpr_end 
_SimLocalCall_ 


asm jmp vpr_Cal (Putter 


vpr_end: 
asm pop Es 


return totalSent; 


local, nested functions are placed here iat | 
clobbers AX. ES *must* be defined in all models. 


vpr_strlen: 

asm push 

asm mov 

asm mov 

asm repne 

asm not /* (mot CX) == (-1 -CX) */ 
/* scasb overshoots */ 


scan string ES: [DI] up to \0 */ 


count the string length. */ 


/* skip the jmp after SimlocalCall_ */ 
jmp /* CX = string length */ 
RETWEAR =i 


Put character to next postion in S, check for S$ full nibs ai 
clobbers AX. 


vpr_PutTos: 
asm mov BYO (SS_ [di]), al 
asm inc di 
dec BYO (Scount) 
ing vpr_Cal Putter 
pop 8x 
add ax, 3 /* skip the jmp after SimLocalCall_ */ 
jmp ax /* CX = string length */ 
RETNEAR s7 


call “putter to flush S 
clobbers AX. 


vpr_Cal (Putter: 
asm bx 
asm cx 
asm dx 
Es 
asm ax, $ 
di, ax /* count chars in S$ */ 
putter (S, DI, outP); 


Scount = Ssize; 
totalSent += _DI; 


le di, § 
pop Es 
pop dx 
pop cx 
pop bx 
Pop 

add 


/* skip the jmp after SimlocalCall_ */ 
/* CX = string length */ 


imp 
RETNEAR */ 


end of embedded functions 
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ARCHIMEDES’ 
NOTEBOOK 


Choosing the most cost-effective lens 
design is easy with Eureka! 


Milton C. Kurtz 


ewton postulated that 

light, as a stream of par- 

ticles, travels in straight 

lines. This theory 
makes optical problems solvable 
using simple geometry, or more 
specifically, by applying geometrical 
optics (see accompanying sidebar). 
One application particularly well- 
suited to geometrical optics is the 
lens problem. We will examine the 
behavior of a thin lens, and use 
Eureka to determine the most 
cost-effective way to design a thin 
lens for a given application. 


DESCRIBING A THIN LENS 


First, we will present some defini- 
tions to describe our lens. 


Index of Refraction. A light ray is 
bent, or refracted, when it passes 
from one medium, such as air, 
into another medium of different 
density, such as glass. The ability 
of a medium to bend light rays is 
its index of refraction, which is a 
ratio of the velocity of light in a 
medium compared to the velocity 
of light in a vacuum. (This subject 
has been investigated thoroughly 
by Snell, and the refraction of 
light follows Snell’s Law.) 


Thin Lens. A thin lens is a lens 
whose thickness is small com- 
pared with its other features (e.g., 
focal length). 

Focal Point. The focal point of a 
lens is a point on the axis having 
the property such that any ray 


coming from it, or proceeding to 
it, travels parallel to the axis after 
refraction. 


Focal Length. The focal length of a 
lens is the distance between the 
focal point on the axis of the lens 
and the center of the lens. 


Axis. The axis of the lens is a 
straight line passing through the 
geometrical center of the lens, 
perpendicular to the radii of 
curvature. 

A lens has two focal points; 
each focal point is equidistant 
from the center of a symmetrical 
lens. The focal point defined 
above is the primary focal point; the 
other focal point is the secondary 
focal point. Light traveling parallel 
to the axis will, after refraction, 
proceed toward—or appear to 


Primary 
focal 
point. 


—_ f/f ees: 


emanate from—the secondary 
focal point. 

If we designate fas the primary 
focal length in a symmetrical lens, 
and f’ as the secondary focal 
length, then f=’. These condi- 
tions are shown in Figure 1. 

If we know the focal length of 
a thin lens and the position of the 
object being viewed through the 
lens, we can find the position of 
the object’s image by one of three 
methods: graphical construction, 
experimentation, or use of the 
lens formula. 


THE LENS FORMULA 


The lens formula is readily de- 
rived from the geometry of Figure 
2. The diagram shows two rays 
leading from the object of height y 


Secondary 
focal point 


—— /'—> 


Figure 1. Two views of a thin lens with rays from and to F and F’, 


respectively. 


: : : : C’ 
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to the image of height y’. Let s 
represent the object distance from 
the center of the lens and let s’ 
represent the image distance from 
the center of the lens. x represents 
the object distance from the 
focal point F, and x’ represents 
the image distance from focal 
point F’. 

From similar triangles C’DE and 
F’DA, the proportionality between 
corresponding sides gives: 


crag! (1) 


y - 9 is used instead of y + y’ 
because y’, by the convention of 
signs, is a negative quantity. Also, 
from the similar triangles CDE 
and FAB, we can derive the 
relationship: 


al eer 
s f 


The sum of these two equations 
yields: 


(2) 


, , , 


2 


ae 
: a eee 


Since f= f’, the two terms on the 
right may be combined and y - 9’ 
canceled out, resulting in the 
equation: 


(3) 


an! 
=F (4) 


This equation is the lens formula, 
where s is the object distance, s’ is 
the image distance, and fis the 
focal length of the lens. Object 
distances are positive if the object 
lies to the left of its reference 
point A, and image distances are 
positive if the image lies to the 
right of reference point A. 

Now that we know the relative 
positions of the object and image, 
it’s easy to determine their sizes. 
The lateral magnification is: 


7 


» 


5° 
ss hanes 


5 
7 (5) 


When s and s’ are both positive, 
the negative sign of the magnifica- 
tion denotes an inverted image. 
The images formed by the lens 
in this exercise are real in that 
they form a visible image on a 
screen. Real images are formed 
when the rays of light are actually 
brought to focus in the plane of 
the image. Other conditions will 
form a virtual image, or one that 
cannot be formed on a screen. In 
a virtual image, the rays from a 
given point on the object do not 
come together at the correspond- 
ing point in the image. They must 
be projected backward to find the 
image plane. Virtual images are 
produced by converging lenses 
when the object is placed between 
the focal point and the lens. This 
condition is shown in Figure 3. 


The power of a 
thin lens (in units 
known as diopters) 
is given as the 
reciprocal of the 


focal length 


expressed in meters. 


*& eocccccccocce ge 


s 
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One other point of interest is 
the determination of the power of 
a lens. The power of a thin lens 
(measured in units known as diop- 
ters [D]) is given as the reciprocal 
of its focal length (expressed in 
meters). 


f (6) 


For example, a lens with a focal 
length of +25 centimeters has a 
power of 1/0.25 meters or +4.0 D. 
These units are used in optome- 
try, and can be found on your eye- 
glass prescription or stamped on 
the inside of the temple bow on 
reading glasses. 


CHOOSING A LENS 


We now have the formulas and 
background information that we 
need in order to choose a lens for 
use in applications such as those 
involving the observation of an 
object located at a fixed distance 
from the lens. A number of differ- 
ent focal lengths are possible and 
the image distance varies, so we'll 
set up the lens formula in Eureka 
to determine the image distances 
that pertain to a range of focal 
lengths. Of course, we could set 
up this problem in a language 
such as Turbo Basic, where all sys- 
tem constraints, as well as the vari- 
ables to be considered, are called 
out. However, Eureka allows us to 
quickly model the lens problem 


continued on page 152 


Figure 3. Placement of an object between the focal point and the lens, creating a 


virtual image. 
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NOTEBOOK 
continued from page 151 


without worrying about program- 
ming details. 

As a more concrete example, 
let’s use an optical inspection 
instrument to observe a row of 
slots that are machined into a rod. 
We want to determine the width of 
the slots, along with the distance 
between them. (For simplicity’s 
sake, we'll look only at the optics 
here, disregarding the usual 
mechanisms that are involved in 
holding and supporting an 
object.) The only constraint we'll 
put on the system is that we can- 
not get closer than six inches 
from the slots because of interfer- 
ing mechanisms. We now have a 
two-part problem to solve—we 
need to select the best focal 
length in order to project an 
image of the slots onto an appro- 
priate sensor, and we need to 
determine the location of the 
sensor. 

This is a simple statement of 
the problem, but additional infor- 
mation must be considered (such 
as the resolution that we want in 
the measurement). In addition, 
only a finite number of focal 
length lenses is available from 
suppliers; others must be specially 
ordered (a very expensive consid- 
eration). Thus, we want to choose 
our lens from a standard catalog. 


SOLVING IT WITH EUREKA 


To set up the problem in Eureka, 
we'll slightly rewrite Equation 4. 
Let p represent the object dis- 
tance, q represent the image dis- 
tance, and f represent the focal 
length. The new lens equation is: 


] rm eel 

pq ff 

This is the standard form of the 
lens equation. 

After loading Eureka, choose 
Edit and enter the lens formula. 
Add the constraint p = 25. Next, 
select a series of standard focal 
lengths from a supplier’s catalog 
and set f to those values. Table 1 
shows a list of image distances for 


(7) 
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Focal Length f 


Image Distance q 


7.0 mm 9.72 mm 
8.0 mm 11.75 mm 
10.0 mm 16.67 mm 
12.7 mm 25.81 mm 
14.2 mm 32.87 mm 
15.0 mm 37.25 mm 
18.0 mn 64.29 mm 


Table 1. List of image distances for given values of the focal length. 


1/p + 1/q = 1/f 


p = 25 

f =7 

Solution: 

Variables Values 

f = 7.0000000 
p ~ 25 .000000 
q = 9.7222222 


Figure 4. Solution generated by Eureka to find the image distance for a given 


focal length. 
Only a finite 
number of focal 
length lenses is 
available from 
suppliers; others 
must be specially 
ordered, which is a 
very expensive 
proposition. 


given values of the focal length. 

Choose the first focal length 
listed in Table 1, and set f = 7. 

Now, escape from the Edit 
mode and choose Solve. As 
Eureka solves the lens equation, 
we find that q is easily obtained 
for each value of f. When f= 7, 
the image distance q is approxi- 
mately 9.72 millimeters. Figure 4 
shows a solution generated from 
this run. 

We can easily choose an image 
distance for a given focal length, 
but how do we choose the right 
image distance? Equation 5 shows 
that the ratio of the image dis- 
tance to the object distance pro- 
vides a measure of the magnifica- 
tion of the system. Let’s assume 
that it would be desirable to have 
the image be approximately two 
times the size of the object. Set up 
that ratio in Eureka, without speci- 
fying a focal length f: 
qj/p=2 
Given an object distance of 25 mil- 
limeters, we see that the ideal 
focal length is 16.67 millimeters, 
and the image distance is 50 mil- 
limeters. However, because this is 
a nonstandard focal length, it’s 
not desirable. The two standard 


focal lengths of 15 and 18 millime- 
ters are close, so let’s examine 
them more carefully. 

We specified earlier that we 
could get no closer than 25 mil- 
limeters from the object. When we 
set the focal length to 15 at a mag- 
nification of 2, the object distance 
is 22.5 millimeters and the image 
distance is 45 millimeters. 


Equation 5 
shows that the ratio 
of the image dis- 
tance to the object 
distance provides a 
measure of the 
magnification of 
the system. 


Again, this does not meet our 
requirement that the object dis- 
tance be at least 25 millimeters. 
When we change the focal length 
to 18 millimeters, the object dis- 
tance becomes 27 millimeters, and 
the image distance becomes 54 
millimeters. Clearly, the 18 mil- 
limeter lens meets all the require- 
ments of the system. 

The short history of optics 
included in the accompanying 
sidebar, along with this simple 
geometrical optics application, 
should help make optics a less for- 
midable area. We did not touch 
on physical optics, where Eureka 
can play a much greater role in 
easing the workload of the system 
designer who deals with the com- 
plex equations of that field. @ 


Milton C. Kurtz is a 1946 graduate 


of the University of Maryland. He has 
spent most of his career in applied 
science and instrumentation develop- 
ment. Now retired, he is a director of 
Emkay Engineering, Inc., of Sara- 
toga, California. 


THE DUALITY OF LIGHT 


The fundamental picture of the 
way we view light has changed 
significantly during the last 300 
years. Isaac Newton defined light 
as a stream of particles in his 
basic treatise OPTICKS, printed 
in 1704. Because of his stature as 
a scientist, his hypotheses were 
supported by his contemporaries 
and successors. This corpuscular 
theory of light was generally ac- 
cepted for almost a century. 
However, Newton also noticed 
that light exhibits some “wave- 
like characteristics” —called 
“Newton’s Rings’”—during his 
experiments with glass plates 
and thin films. These “Rings” 
cast considerable doubt upon 
the corpuscular theory as the 
sole answer for the understand- 
ing of light. 

In 1803, Thomas Young 
observed that a monochromatic 
light beam passing through two 
pinholes produces an interfer- 
ence pattern much like the pat- 
tern of waves in water. His ob- 
servation lent support to the 
wave theory of light, which was 
expressed earlier by Christian 
Huygens. Another fact already 
known about the behavior of 
light was that two kinds of wave 
propagation exist in a medium— 
longitudinal waves, which consist 
of compressions and rarefac- 
tions in that medium as exhib- 
ited by sound waves; and trans- 
verse waves, as demonstrated by 
wave propagation in water and 
electromagnetic waves. Augustin 
Jean Fresnel and Dominique 
Francois Arago reviewed this 
information and other work to 
date and clearly demonstrated 


that light must consist of trans- 
verse waves oscillating at right 
angles to their direction of 
propagation. 

This important development 
fit James Clerk Maxwell’s electro- 
magnetic theory of light, which was 
postulated later in the 1800s. 
Maxwell described light as a 
“rapid variation in the electro- 
magnetic field surrounding a 
charged particle, the variations 
in the field being generated by 
the oscillation of the particle.” 

In Maxwell’s theory, light 
takes its place along with other 
forms of radiant energy as an 
aspect of the fundamental phe- 
nomenon of electromagnetism. 
The study of physics over the last 
100 years has indicated that 
while the fundamental associa- 
tion of light with electromagne- 
tism has held firm, the nature of 
the understanding of that associ- 
ation has undergone some 
changes. Light, even though it 
demonstrates such wave-like 
phenomena as interference and 
polarization, also interacts with 
matter as if the light itself con- 
sists of a stream of individual 
bundles—called photons—with 
their own energy and momen- 
tum. So, what is light? Except for 
minor differences, light and mat- 
ter are essentially the same— 
both are made up of particles 
that exhibit wave-like character- 
istics. We must keep this duality 
in mind when considering the 
applications of optics. 


—RMilton C. Kurtz 
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MACH 2 FOR 
TURBO BASIC 


MicroHelp, Inc. 

2220 Carlyle Drive 
Manetta, Georgia 30062 
(404) 973-9272 

$69.95 


peed is of the essence in 

commercial programming. 

And speed is something 

that BASIC programmers 
have traditionally forsaken in 
exchange for BASIC’s easy coding 
and testing. To boost the notori- 
ously slow speed of IBM PC BASIC, 
MicroHelp, Inc., developed Mach 2, 
a set of assembly language subrou- 
tines; Mach 2 is now available for 
Turbo Basic. Even though Turbo 
Basic is much faster than the 
BASICA interpreter, it still benefits 
greatly from Mach 2’s speed 
injection. 

Mach 2’s two diskettes contain 
INC files for the subroutines and a 
copious set of example programs, 
plus a master demo program. The 
manual is organized functionally, 
with a separate chapter for each 
type of Mach 2’s subroutine (screen 


handling, window management, etc.). 


To use Mach 2, you copy the 
INC files to a working directory 
and use the $INCLUDE compiler 
directive to incorporate them into 
your Turbo Basic program. Most 
of the .INC files are inline subrou- 
tines, consisting of unadorned lines 
of hexadecimal constants, and can- 
not be readily modified by the user. 
Assembler source code for the rou- 
tines is available separately, but 
since the routines work as docu- 
mented in the manual, the source 
code is unnecessary for most users. 

Mach 2 provides more than 34 


CRITIQUE 


routines that handle a variety of 
functions, including screen man- 
agement (reading and writing char- 
acters directly to screen memory), 
window management, file and 
device management, user input, 
sorting, and menus. In particular, 
the string input routine is unusually 
fast and flexible, with 16 calling 
options. Using this single input rou- 
tine, the programmer can control 
the cursor’s shape (with different 
shapes for insert and typeover 
modes), text colors, fill characters, 
field length, and field exit criteria. 

Some of Mach 2’s more unusual 
(and useful) functions include large 
character displays (multiline charac- 
ters made out of the PC’s line-draw 
characters, useful for titles and 
warnings); Soundex codes (hashing 
a string into its phonetic equivalent, 
useful for searching for names that 
sound alike but are spelled differ- 
ently); and Lotus-Intel-Microsoft 
(LIM) Expanded Memory handling. 
Mach 2 also provides routines for 
storing strings in reserved memory, 
which consists of dynamic arrays 
that are allocated from within a 
Turbo Basic program and used to 
hold strings. This use of reserved 
memory for strings works around 
Turbo Basic’s 64K string space lim- 
itation, and could prove a godsend 
to programmers writing large appli- 
cations. The master demo program 
demonstrates each subroutine’s 
capabilities to good effect. 

Even when using all the subrou- 
tines provided, programmers who 
write business applications will still 
need a file access manager (such as 
the Turbo Basic Database Toolbox) 
in order to develop complete busi- 
ness applications. 

Mach 2’s documentation is good, 
and offers many hints on improv- 
ing the performance of Turbo Basic 


code and using the Mach 2 subrou- 
tines. Handy reference sections list 
the subroutine calls, and the sam- 

ple programs are well documented. 

While the performance of Mach 
2’s assembly language subroutines 
is striking, there is a price to be 
paid—the interface to them is more 
fragile than that of subroutines writ- 
ten in Turbo Basic alone. For 
example, single- and double- 
precision floating point numbers 
cannot both be passed interchange- 
ably to Mach 2’s routines, so careful 
declaration of a variable’s type is 
necessary. Nor can constants or 
dynamic arrays be passed. The type 
and number of parameters to each 
CALL statement must exactly match 
the documented parameters for 
that statement, otherwise what the 
Mach 2 manual euphemistically 
calls “unpredictable results” will 
occur. Finally, careful initialization 
and termination of the routines is 
required. The manual clearly spells 
out these limitations, but novice 
programmers might have trouble at 
first, since Mach 2 requires more 
discipline than is needed for nor- 
mal Turbo Basic programming. 

There is one niggling flaw in 
Mach 2— it requires interrupt 66H 
for passing information between 
the Turbo Basic program and the 
assembly language routines. Some 
way to alter Mach 2’s interrupt 
number should be provided. 

But when Mach 2 is set up cor- 
rectly, the results can be dramatic. 
If you need the functions it pro- 
vides, and you don’t mind writing 
your Turbo Basic code with a bit 
more discipline than usual, this 
assembly language subroutine 
package comes highly rec- 
ommended. @ 


—Marty Franz 
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C-SCAPE WITH 
LOOK AND FEEL 


The Oakland Group, Inc. 

675 Massachusetts Avenue 
Cambridge, MA 02139 

(800) 233-3733 or (617) 491-7311 
$99.00 


ne of the major differ- 
ences between desktop 
computers and their 
mainframe brethren is 
that the small machines must cater 
to naive users. This creates a pro- 
gramming challenge—many desk- 
top computer users who have 
grown up with applications such as 
Paradox and WordStar also expect 
easy-to-use, friendly interfaces for 
custom or inhouse software. 

In G, this user interface chal- 
lenge poses a problem, because the 
C language supports no standard 
user interface other than the oper- 
ating system’s command line. 
Sooner or later, most serious C soft- 
ware developers must face the task 
of writing a library of C functions to 
get input from, and to present out- 
put to, the user. When that time 
arrives, “canned” libraries of com- 
plete and tested user interface func- 
tions can prove useful—C-scape 
from The Oakland Group is such 
a product. 

C-scape contains a library of 
functions that implement a user 
interface, and a screen designer 
program, called Look and Feel, that 
automates the coding of screens, 
borders, and input fields. The 
Turbo C programmer can use 
C-scape to incorporate menus, win- 
dows, and input fields into a pro- 
gram with a minimum of fuss. 
C-scape is available for most popu- 
lar PC-based C compilers; the 
Turbo C version, “turbo priced” at 
$99, includes the function library 
object modules, the Look and Feel 
utility, and bulletin board support. 
It is shipped as a 500-page perfect 
bound manual and five diskettes. A 
$180 upgrade to source code and 
full telephone support is also 
available. 

To use C-scape, you place the 
appropriate #include statements 
and function calls into your Turbo 
C program, and then compile and 
link with the C-scape header files 
and libraries. As an alternative to 
coding these statements manually, 
the Look and Feel screen designer 


can be used to design the screens 
interactively, and then to automatic- 
ally generate the calls to the appro- 
priate C-scape library routines. As a 
third option, C-scape can import 
screens created with Dan Bricklin’s 
Demo Program. 

The Look and Feel screen 
designer uses the C-scape user 
interface, and provides a good 
example of what can be done with 
C-scape in a production program. 
The screen designer allows you to 
type characters and lines in true 
WYSIWYG (What-You-See-Is-What- 
You-Get) fashion, to draw borders 
and backgrounds, and to create 
menus. Once you're happy with 
what you see, you can generate 
source code from the completed 
screen. Commands are activated 
from a menu that pops up when 
F10 is pressed; or through hot keys 
(a necessary option, given the 
infrequent-then-intense use that 
this type of program receives). Look 
and Feel also contains a complete 
help facility. A nice feature of Look 
and Feel that is not found in many 
other screen designers is the ability 
to create screens larger than 80 X 
25 with support for horizontal and 
vertical scrolling. This feature 
allows developers to support screen 
formats such as the EGA 43-line 
and VGA 50-line formats; and to 
support large text screens like the 
Micro Display Systems Genius VHR 
66-line display. 

The C-scape library is built in 
two levels. The higher level of the 
library has functions for entering 
fields of text, phone numbers, cur- 
rency, dates, times, and so forth. An 
applications programmer will prob- 
ably use these functions most fre- 
quently. Several different types of 
menus are supported at this level, 
including the familiar Lotus-style 
“moving bar,” pulldown menus, 
and pop-up menus. A help facility 
can be incorporated into programs 
to allow the creation of text files for 
display when the user presses the 
F1 key. C-scape’s sophisticated help 
facility contains highlighted key- 
words with cross references to 
other screens. Miscellaneous utility 
functions handle such activities as 
word-wrapping text in a string. 

The lower level of the C-scape 
library controls the software objects 
that the higher level uses. These 


objects include menus, fields, and 
“seds,” which are screen windows 
with customizable properties such 
as borders and titles. The lower- 
level functions are most useful for 
hardcore product developers who 
want a unique “look and feel” for 
their product. The C-scape library 
makes heavy use of pointers to 
functions; the lower level of the 
library supports replacement of 
these functions to handle custom 
field validation and keystroke trans- 
lation. Another portion of C-scape’s 
lower-level functions is a screen 
driver, which can be customized to 
handle nonstandard PC displays. 
(It’s illuminating to run the RAM 
screen driver and the BIOS-only 
screen driver consecutively to com- 
pare their performance!) 

The C-scape library works well in 
actual use. The higher-level func- 
tions are rich; in fact, many Turbo 
C programmers will never need to 
use the lower-level functions. The 
menufunPrintf() function in partic- 
ular is nicely done—strings similar 
to those used by printf) handle 
cursor positioning, color changes, 
and printable and nonprintable 
characters with a powerful, if con- 
cise, syntax. Since the C-scape func- 
tions all religiously use the screen 
driver, they're portable among var- 
ious types of PC hardware. In addi- 
tion, when the RAM driver is used, 
C-scape’s functions are fast. The 
product’s documentation is well- 
written and fully indexed, and de- 
scribes each call in some detail. 

C-scape suffers from a few draw- 
backs. Its construction, while flexi- 
ble, may be too complex for modifi- 
cation by beginning or casual C 
programmers. Also, C-scape’s docu- 
mentation describes the lower-level 
functions before discussing the 
higher-level ones; this could prove 
initially overwhelming to less- 
advanced programmers. 

But building a good user inter- 
face is what C-scape is for, and 
that’s what it accomplishes. Profes- 
sional C programmers and consul- 
tants would do well to evaluate 
C-scape before undertaking their 
next screen-intensive project. 


—Marty Franz 
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TURBO C PROGRAMMING 
FOR THE IBM 


Robert Lafore, Howard W. Sams & 
Company, Indianapolis, IN, ISBN 
0-672-22614-6, 585 pages, softcover, 
$22.95. 


he first half of this un- 
usually comprehensive 
book offers an excellent 
introduction to the 
Turbo C environment and to C pro- 
gramming in general. The second 
half of the text covers a wealth of 
progressively more advanced Turbo 
C topics (such as memory models, 
pointers, and advanced variables), 
which provide interesting reading 
for both the novice and the more 
experienced Turbo C programmer. 

Chapter | presents a step-by-step 
guide to Turbo C’s integrated devel- 
opment environment, and walks 
the reader through the process of 
creating a simple Turbo C program. 
The author then discusses the dif- 
ferent types of files (header, library, 
runtime, math, and programmer- 
generated) that are required to 
build a C program. In this chapter, 
Lafore provides easily understood 
explanations of basic concepts, and 
doesn’t make the common mistake 
of assuming that the reader under- 
stands the linking process and the 
use of header files. 

The second chapter introduces 
the building blocks of Turbo C pro- 
grams: variables, I/O functions, 
and operators. In the following 
three chapters, Lafore uses these 
building blocks to explore the con- 
trol statements of Turbo C in an 
informative discussion of loops, 
decisions, and functions. 
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for the IBM’ 


Robert Lafore 


The next two chapters focus on 
those areas where C differs most 
from other compiled languages. 
Array declaration, content, initial- 
ization, size, and sorting are pre- 
sented in Chapter 6, along with a 
discussion of string variables, ini- 
tialization, and I/O functions. The 
explanation on copying strings into 
an array of strings is particularly 
interesting. 

The discussion on pointers in 
Chapter 7 skillfully explains what is 
often regarded as one of the most 
difficult concepts to master in C. 
Lafore starts with a lucid introduc- 
tion to the need for pointers in 
Turbo C, and moves on to cover 
the mechanics of pointer usage. 
This chapter is required reading 
even for the very experienced 
Turbo Pascal programmer, because 
C handles pointers differently than 
does Turbo Pascal. 

The last seven chapters of the 
book address more advanced pro- 
gramming topics such as extended 
keyboard codes, cursor control, 
command-line arguments, struc- 


tures, unions, ROM BIOS routines, 
memory and the character display, 
color graphics, and disk I/O opera- 
tions. Lafore devotes a chapter to 
the creation of larger programs in 
Turbo C, and covers separate com- 
pilation, conditional compilation, 
and memory models. The book’s 
final chapter examines advanced 
variables (register variables, enu- 
merations, and storage classes). 

Throughout the text, Lafore 
emphasizes a practical, hands-on 
approach to programming con- 
cepts, and includes a wealth of 
clear and concise program exam- 
ples. Important facts are visually 
highlighted in gray boxes through- 
out each chapter. All chapters end 
with a summary, followed by a set 
of exercises that is designed to help 
the reader apply his/her newfound 
knowledge (answers are included 
in the back of the text). Appendices 
include references, hexadecimal 
numbering, a bibliography, and an 
ASCII chart. 

As an added plus, Lafore often 
provides helpful solutions to prob- 
lems that a C programmer will typi- 
cally encounter. For example, the 
discussion of color graphics intro- 
duces direct memory access by 
presenting relevant examples such 
as the use of ROM routines to plot 
points in graphics modes. The 
“Files” chapter presents an impres- 
sive discussion of text mode versus 
binary mode. 

This book offers an excellent 
presentation of programming con- 
cepts and example programs for 
both beginning and more ad- 
vanced C programmers, and is a 
valuable addition to any Turbo C 
programmer’s book shelf. @ 

—Robert Alonso 


ARTIFICIAL INTELLIGENCE 
PROGRAMMING WITH 
TURBO PROLOG 


Keith Weiskamp and Terry Hengl, John 
Wiley & Sons, Inc., New York, NY: 
1988, ISBN 0471-62752-6, 262 pages, 
soft cover, $22.95, disk $24.95. 


f you are one of the many 

newcomers to the field of 

Artificial Intelligence pro- 

gramming, you may be dis- 
covering that learning Turbo Prolog 
and reading books about basic 
Prolog concepts are not enough to 
get you started on developing AI 
applications. Many programmers 
who have explored Turbo Prolog 
and even written a few short pro- 
grams may still feel handicapped 
when trying to apply that knowl- 
edge to the development of a 
serious AI application. 

Until now, this scenario could 
have been attributed, at least in 
part, to the absence of books on Al 
fundamentals as they relate to 
Turbo Prolog. Most books on the 
market today emphasize Prolog 
programming theories and tech- 
niques, rather than the world of 
Artificial Intelligence and related 
concepts. None of these books has 
attempted to illustrate the funda- 
mentals of AI using Turbo Prolog— 
that is, until Artificial Intelligence Pro- 
gramming with Turbo Prolog, written 
by Keith Weiskamp and Terry 
Hengl. This book has a very spe- 
cific goal—to show you how to use 
Turbo Prolog to develop AI applica- 
tions. The authors seem to have 
spent a great deal of effort in stay- 
ing with this game plan. 


OPENING THE WINDOW 


The book has a pleasant, readable 
style. The authors begin by “Open- 
ing the AI Window’ to let you peek 
into the world of AI applications. 
The first two chapters in the book 
also cover features of Turbo Prolog. 
However, instead of regurgitating 
the information in the Turbo Prolog 
Owner's Handbook, the authors focus 
on the way that Turbo Prolog works 
and cover such topics as the Reso- 
lution Principle, unification, back- 
tracking, and nondeterministic 
programming. 


Artificial 
Intelligence 
Programming 


Turbo 
Prolog 


KEITH WEISKAMP 


TERRY HENGL 


Chapter 3 provides an introduc- 
tion to software design using Turbo 
Prolog. Here, the authors illustrate 
techniques for developing an AI 
toolbox—a collection of subrou- 
tines (predicates) that are essential 
to developing AI applications. For 
example, if you have some expe- 
rience with a procedural language 
like Pascal or C, you know that you 
need to develop some routines for 
controlling program flow. One such 
control structure that is essential in 
large scale applications—the 
repeat/ fail loop—is covered in the 
book. Similarly, the authors provide 
predicates to process various Prolog 
data structures, such as characters, 
strings, and lists. A section is also 
devoted to the role of recursion in 
Turbo Prolog programming. 


LAYING THE GROUNDWORK 


The remaining four chapters in the 
book develop the groundwork for 
AI programming. In Chapter 4, the 
authors discuss the development of 
an inference engine, including the 
fundamentals of reasoning as a 
process of both categorizing infor- 
mation in the form of known facts 
and rules (knowledge), and creating 
new facts and rules. Perhaps the 
most important concept in this 
chapter is that of formal reasoning 
using propositional and predicate 
calculus. The authors follow the 
discussion on propositional calculus 
with an example (the Translate pro- 
gram) that illustrates how Turbo 
Prolog could be used with formal 
propositional logic. The chapter 
concludes by explaining forward 
and backward chaining, which are 
the control strategies used in build- 
ing an inference engine, along with 


the actual construction of the core 
of an inference engine (a sched- 
uler, a rule interpreter, and the 
knowledge interface.) 

Chapter 5 provides an in-depth 
look at natural language process- 
ing. The reader is presented with 
natural language processing tech- 
niques, including pattern matching. 
The discussion of transition net- 
works includes both augmented 
and recursive transition networks. 
Example programs illustrate each 
of these techniques. 

One of the most critical factors 
in the development of expert sys- 
tems is the representation of facts 
or knowledge, since knowledge 
comprises the actual data in a 
Prolog program. Chapter 6 explores 
various techniques used in AI pro- 
grams for representing knowledge, 
including specific knowledge 
representation features in Turbo 
Prolog. The chapter also includes a 
discussion of knowledge represen- 
tation with frames and provides an 
example of such a representation 
in Turbo Prolog. 

The book’s final chapter takes 
you through the various develop- 
ment stages of an expert system. 
The authors explain various char- 
acteristics and types of expert sys- 
tems, and provide hints about tech- 
niques for improving the example 
expert system. 

Artificial Intelligence Programming 
with Turbo Prolog provides you with 
basic Turbo Prolog concepts, and 
helps you build AI tools, by primar- 
ily focusing on the groundwork 
needed for programming AI appli- 
cations. It is not (necessarily) a 
beginner’s book about Turbo 
Prolog, and doesn’t attempt to 
replace your Owner's Handbook or a 
tutorial/reference guide. For users 
who are ready to make the jump 
into real-world AI applications, Arti- 
ficial Intelligence Programming with 
Turbo Prolog should prove quite 
valuable. @ 


— Sanjiva Nath 
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TURBO RESOURCES 


COMPUSERVE 


The best online information about 
the Borland languages can be found 
on CompuServe’s three Borland 
forums. Quite apart from providing 
the listings appearing in TURBO 
TECHNIX, the Borland forums con- 
tain megabytes of utilities and 
source code in all Borland lan- 
guages. 

Subscribing to CompuServe can 
be done through the coupon en- 
closed with every Borland product 
(which also includes $15 worth of 
free online time for your first 
month) or by calling CompuServe at 
(800) 848-8199. You’ll need a modem 
and communications software that 
supports XMODEM file transfers. 

Learning your way around 
CompuServe takes some time and 
practice, but good books have been 
written about it, including Charles 
Bowen’s and David Peyton’s How To 
Get The Most Out Of CompuServe and 
Advanced CompuServe for IBM Power 
Users (New York: Bantam Computer 
Books, 1986.) Howard Benner’s 
TAPCIS shareware utility can help 
you automate sessions and minimize 
connect time. It’s available for down- 
loading on CompuServe from DL 12 
of the WordPerfect Support Group 
Forum (GO WPSG). The TAPCIS 
file is 239,297 bytes long—plan to 
spend some hours downloading it. 


How to access the Borland 
Forums on CompuServe: 


TURBO TECHNIX listings for Turbo 
Pascal and Turbo Basic are available 
in DL 1 (Data Library 1) of the 
BPROGA Borland Programming 
Forum (GO BPROGA). Turbo C and 
Turbo Prolog listings are stored in 
DL 1 of the BPROGB Forum (GO 
BPROGB). Listings for Business 
Language articles are also available 
in DL 1 of the Borland Applications 
Forum (GO BORAPP). From the 
initial CompuServe prompt, type 
GO <forum name> or follow the 
menus. If you are not already a 
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member of a forum, you must join 
by following the menus before you 
can download the listing files. 


How to download TURBO 
TECHNIX code listings 
from CompuServe: 


At the Functions prompt, type: DL 1. 
This will take you to the TURBO 
TECHNIX data library, where all list- 
ing files are stored. Listing files are 
archived using the ARC52 archiv- 
ing scheme. You will need the 
ARC-E.COM program (available in 
DL 0 of BPROGA, BPROGB and 
BORAPP) or one compatible with it 
to extract listing files from down- 
loaded archives. 

Archive files are organized two 
ways: by article and by issue. In 
other words, there will be one ARC 
file for every article that includes 
listings; and a single, larger ARC 
file for each issue containing all the 
individual .ARC files for that issue. 
You can therefore download listings 
for individual articles, or download 
the entire issue’s listings at once. 

The all-issue files follow a naming 
convention, such as NVDC87.ARC 
(which contains all listing archives 
from the November/December, 1987 
issue), and JAFB88.ARC (for the Jan- 
uary/February, 1988 issue), and so 
on. The name of an article’s individ- 
ual listings archive file is given at the 
end of the article. 

To download an archive file, bring 
up the DL | prompt and type: 

DOW <filename>/PROTO: XMO 


After pressing Enter, start your 

own communications program’s 
XMODEM receive function. After 
you have completely received the 
file, you must press Enter once to 
inform CompuServe that the down- 
load has been completed. Once you 
have downloaded an archive file, 
you can “extract” its component files 
by invoking ARC-E.COM at the DOS 
prompt with: 

C>ARC-E <filename> @ 


YOUR SUBSCRIPTION 


A free 12-month subscription to 
TURBO TECHNIX is yours for the 
asking when you register any of the 
Borland languages (including 
Quattro, Paradox, Eureka, and Sprint) 
or language toolboxes. A subscription 
request card is packaged with each of 
those products—do fill it out and 
return it to be sure you get every issue. 
If your copy of a Borland language 
product was shipped without the sub- 
scription request card, you can also 
use the subscription services card 
bound into this issue. Don’t forget 
your signature and the serial number 
of a qualifying Borland product—we 
need them to grant your free 
subscription. 

If you have moved or changed your 
name, please use the card to provide 
updated information. If possible, at- 
tach the old mailing label to the card. 


NATIONAL USER GROUPS 
TUG 


The national user group for Turbo 
languages is TUG, the Turbo User 
Group. TUG publishes a bimonthly 
journal called Tug Lines that contains 
bug reports, programming how-tos, 
and product reviews. Extensive public- 
domain utility and source code librar- 
ies are available to members. An 
optional multiuser BBS with file 
uploading/ downloading, messaging 
and teleconferencing is available to 
the public. Membership dues are 
$22.00 US/year ($23.72 in Washington 
State); $26.00 Canada and Mexico; 
$38.00 overseas. 


TUG 

PO Box 1510 
Poulsbo, WA 98370 
BBS: (206) 697-1151 


TPro Users 


TPro Users was founded specifically 
to support Turbo Prolog program- 
ming. Their bimonthly newsletter 
contains technical articles, application 
stories, tips and techniques, and more. 
TPro also maintains an electronic bul- 
letin board for source code download- 
ing and message posting. Dues are 
$25.00 US/year; $35.00 overseas. 


TPRO USERS 

3109 Scotts Valley Drive, Suite 138 
Scotts Valley, CA 95066 

BBS: (408) 438-6506 


LOCAL USER GROUPS 


One of the best places to look for 
advice and face-to-face assistance with 
your programming problems is at a 
local user group meeting. Most user 
groups in the larger cities have special 
interest groups (SIGs) devoted to the 
most popular programming lan- 
guages, usually with strong Turbo 
presences. We will be listing some of 
the largest and most active user 
groups in major urban areas across 
the country; obviously, there are thou- 
sands of user groups that we cannot 
list due to space limitations. If no 
listed group is convenient to you, ask 
about local user groups at a local com- 
puter store or check with a faculty 
member at a high school or college 
with a computer curriculum. 


BOSTON COMPUTER SOCIETY 
Information: (617) 367-8080 
BBS: (617) 353-9312 
One Center Plaza 
Boston, MA 02108 


CAPITAL PC USER GROUP (DC) 
4520 East-West Highway, Suite 550 
Bethesda, MD 20814 
C SIG: Fran Horvath 
AI/Prolog SIG: Dick Strudeman 
BASIC SIG: Don Withrow 


CHICAGO COMPUTER SOCIETY 
Information: (312) 942-0705 
BBS: (312) 942-0706 
Pascal SIG: Bill Todd (312) 439-3774 
C SIG: Ed Keating (312) 438-0027 
AI/Prolog SIG: Jim Reed 
(312) 935-1479 
Basic SIG: Hank Doden 
(312) 774-5769 


HAL/PC (HOUSTON) 
Information: (713) 524-8383 
BBS: (713) 847-3200 or 
(713) 442-6704 
Pascal SIG: Charles Thornton 
(713) 467-1651 
C SIG: Odis Wooten (713) 974-3674 
Compiled BASIC SIG: Larry 
Krutsinger (713) 784-9216 
Al SIG (Prolog): George Yates 
(713) 448-7621 


NEW YORK PC USER GROUP, INC. 
Information: (212) 533-6972 
BBS: (212) 697-1809 
40 Wall Street Suite 2124 
New York, NY 10005 


PACS (PHILADELPHIA) 
Information: (215) 951-1255 
BBS: (215) 951-1863 
PACS, c/o Lasalle University 
Philadelphia, PA 19141 


SAN FRANCISCO PC USERS GROUP 
Information: (415) 221-9166 
444 Geary Blvd, Suite 33 
San Francisco, CA 94118 


ST. LOUIS USERS’ GROUP 
Information: (314) 968-0992 
BBS: (314) 361-8662 
Pascal SIG: Jeffrey Watson 
(314) 481-4239 
C/Assembler SIG: David Rogers 
(314) 968-8012 
BASIC SIG: Dennis Dohner 
(314) 351-5371 


TWIN CITIES PC USER GROUP 
Information: (612) 888-0557 
BBS: (612) 888-0468 
PO Box 3163 
Minneapolis, MN 55403 


Independent CBBS systems with 
programming orientation 


Questor Project Washington, DC 


(703) 525-4066  24Hr $ 

Illinois BBS Chicago, IL 
(312) 885-2303  24Hr $ 
PC-TECH BBS _ Santa Clara, CA 
(408) 435-5006 = 24Hr 


$ = membership fee required 


C:>CLASS.ADS 


TURBOGEOMETRY LIBRARY 
Turbo Pascal, C, Mac and Microsoft C 
Over 150 geometric routines that include: 
Intersections of Lines, Arcs, Planes, Circles 
2D and 3D Transformations 
Equations of Lines, Circles, Planes. 
Hidden Line, Perspective, Curves 
Surface Areas & Volume Routines 
Clipping, Composite Matrices, Vectors. 
Distance Computations. 
Decomposition of Concave Polygons 
Req. IBM PC(Comp)/MAC. VISA,MC,MO 
Source Code,Manual for $99.95 +$5 S&H 
Disk Software, Inc. 2116 E.Arapaho #487, 
Richardson, TX 75081 (214)423-7288 


C:>CLASS.ADS is TURBO 
TECHNIX magazine’s display 
classified advertising section. 
We welcome to these pages all 
those who would like to take 
advantage of the special sizes 
and rates available for 
C:>CLASS.ADS—$300 per 
column inch, with a 2-inch 
minimum. (A minimum ad, for 
example, measures exactly 

2 ie” wide by 2” long.) All 
C:>CLASS.ADS must be pre- 


paid and submitted in camera- 
ready form (black and white 
PMT or Velox) to: 


C:>CLASS.ADS 

TURBO TECHNIX 

4585 Scotts Valley Drive 
P.O. Box 660001 

Scotts Valley, CA 95066-0001 


For additional information, 
please call Production Assistant 
Annette Fullerton at (408) 
438-9321. 
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PHILIPPE’S TURBO TALK 


oes a compiler become 
better because it’s pack- 
aged in a huge box and 
sold by weight? Maybe 
you've heard that if some compa- 
nies know that a retailer must 
carry their product, they make the 
package as big as possible to push 
other vendors off the shelf. The 
user community is smart enough 
to see through this. Still, some 
people get caught by surprise. 

Good documentation isn’t the 
same as fat documentation. Docu- 
mentation writers should not get 
paid by the word any more than 
software engineers should get 
paid by the line of code. It’s con- 
tent that counts, of course, and 
we all know that. 


ARE BENCHMARKS USEFUL 
TO REAL USERS? 

Should we compiler vendors opti- 
mize for benchmarks? At Borland, 
we make the conscious decision 
not to do so, but rather to set com- 
piler default settings for conve- 
nience and efficiency. However, 
we've all heard about software 
optimized for benchmarks. How 
about “sieve recognizers?” Maybe 
that’s a joke, but it’s true that some 
business software, and even some 
compilers, are now written so that 
they make the “standard bench- 
marks” look good. Who cares 
about the user? The user never 
runs benchmarks. The only real 
measure of software performance 
is how quickly it gets the user’s job 
done. It’s hard to write a bench- 
mark that takes the real world into 
account. But it should be done, or 
the benchmarks aren’t saying any- 
thing useful. In the meantime, the 
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The new age of software 
craftsmanship. 


Philippe Kahn 


users will, by their natural com- 
mon sense, separate the hype 
from the reality and get their work 
done faster. The real benchmark 
is, “Am I more productive, and is 
the quality of my work higher 
when L use this tool?” 


DO FAST AND SMALL STILL 
COUNT? 


For years we've noticed that 
memory is getting cheaper and 
that processors are getting faster. 
So we’re all excited about the 
wonderful applications that we are 
going to be able to build with this 
increased computing power. We 
all know that software tends to use 
up all available memory, and that 
it also has a tendency to grab all 
the processor time it can. Until 
now, we have all tried to be very 
careful to use hardware resources 
as efficiently as possible. Yet, al- 
though we remember great soft- 
ware that ran in 64K machines 
running 8-bit processors, today we 
consider it almost normal for soft- 
ware to require a 32-bit processor 
and several megabytes of RAM. 
Now, is this because this particular 
piece of software uses the com- 
puter’s resources less efficiently? 
Or is it because the people who 
wrote it were thinking, “After all, 
memory is cheap and processor 
speeds are faster, so who cares?” 
With more memory in almost 
every machine, there’s a tendency 
to write what I call “sloppy soft- 
ware.” Who cares if “Hello, world 
takes 400K if I still have mega- 
bytes left? 

Then there’s the old hype line 
that says, “This machine is so fast, 
it doesn’t matter that the operat- 
ing system is written in interpret- 
ed BASIC.” Guess how fast that 


” 


machine would run if it had a real 
operating system? 

Why is this sort of logic wrong? 
After all, with faster processors 
and cheap memory, do code size 
and execution speed matter? 
Under DOS, of course they do. 
But how about multitasking op- 
erating systems with dynamic 
memory management? Think 
about it: slow applications will 
steal precious time from other 
tasks and slow them down. And 
memory hogs will force the OS 
to constantly swap the other tasks 
to and from disk. It’s even worse 
than under DOS, where a big, 
slow application only penalizes 
itself. In a multitasking environ- 
ment, slow and fat applications 
penalize all the other tasks. Deja 
vu! Small, efficient code matters 
more than ever before! 

Now that the 640K barrier is 
about to be broken, new programs 
will grow to fit available memory 
and processing speed. A color 
paint program on the Mac that I 
was just playing with requires 1.5 
megabytes. The first MacPaint ran 
in 128K. Is the new program ten 
times better than the original? I 


‘| don’t think so. 


ENTER THE NEW AGE OF 
SOFTWARE CRAFTSMANSHIP 


Remember the scene on the sink- 
ing Titanic, when the passenger 
yelled to the drink steward, “Yes, 
I know I rang for ice, but this is 
ridiculous!” Size and speed, qual- 
ity documentation, and “real 
world optimizations” will matter 
more and more. If we keep that 
in mind, we are going to witness 
a new age of software crafts- 
manship. @ 
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~ Unit Librarie 
» Assembler ie 
= 1/0 Code Generatic 
_ Window Code Generation 
_ Window Management 
= Special Effects 
' Screen Support 
« System Integration 
« User Color Selection 


© Run-Time Dynamic Menus 


« Universal Menus 


= Window & Menu Compression 
© Transparents and Shadows 
= Keyboard Support 


= Cursor Support 
= Field l/O Routines 
= Reentrant Routines 
= Diagnostic Tools 
= File Handling 
= System Resources 
= Sound Effects 
® Critical Error Handlers 
= Automatic Directories 
= Sample Programs 
= Complete Pop-Up Help 
= 280 Page Illustrated Manual 


Nostradamus Inc. 

3191 South Valley Street (Suite 252) 
Salt Lake City, Utah 84109 

(801) 487-9662 

Data/BBS 801-487-9715 1200/2400,n,8,1 


Visa, Amex, C.O.D., Check or P.O. 

60-day satisfaction, money-back guarantee 
Demo Diskettes and brochures available 
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inguage Standard is TURBO PASCAL 4.0 
cement Standard is TURBO PLUS 5.0 


“Turbo Plus 5.0 gives every Program ae 
professional touch. . . saves hours of ~~ 
A must in my programming.” 


Mike Cushman « Former Editor, “*.*,” PC Weill 


“After spending hundreds upon hundreds of dollars searching 
through many utilities and libraries, I must say that 
Nostradamus is my choice!” 


Mr. Paul Mayer + ZPAY Payroll Systems ¢ Franklin Park, IL 


“I've tried most similar products on the market, Turbo-Plus with Screen 
Genie is clearly superior.” 


Dr. David Williamson * Chiropractic Health Services * Durnam, NC 


“This is, without a doubt, the most powerful and easy to use programming toolbox that 
I have seen for the PC environment, and Turbo Pascal in particular.” 
Mr. John Drabik * Geotron International, Inc. * Salt Lake City, UT 


“Your products are first rate. Your Turbo-Plus products give my humble efforts a touch 

of class and speed that I would never have achieved otherwise. Obviously your products 

make Turbo Pascal a much better product.” i 
Mr. L.M. Johnson * Saguaro Technical Services * Cave Creek, AZ : 


Borland-Oshorne/ McGraw-Hill Presents 
The Official Books on TURBO C; TURBO BASIC,” & TURBO PASCAL" 


“The technical depth and timeliness of books in the Borland-Osborne/McGraw-Hill Programming Series provide 
excellent supplementary support for Borland’s best-selling compilers. Users at all levels can turn to these books 
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to help them get the most out of Turbo Pascal, Turbo C, and Turbo Basic.” 
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Using Turbo C° 

by Herbert Schildt 

For all C programmers, beginners to pros, this excellent 
guide helps you write Turbo C programs that get profes- 
sional results. 


$19.95 Paperback, ISBN: 0-07-881279-8, 431 pp., 7% x 9% 
Borland-Osborne/McGraw-Hill Programming Series 


Advanced Turbo C* 


by-Herbert Schildt 

Unveils Turbo C power programming techniques to serious 
programmers. Covers Turbo Pascal conversion to Turbo C 
and Turbo C graphics. 


$22.95 Paperback, ISBN: 0-07-881280-1, 397 pp., 7% x 9 
Borland-Osborne/McGraw-Hill Programming Series 


Turbo C": THE COMPLETE REFERENCE 


by Herbert Schildt Covers Version 1.5 
Programmers at every level of Turbo C expertise can quickly 
locate information on Turbo C functions, commands, 

codes, and applications —all in this handy encyclopedia. 


$24.95 Paperback, ISBN: 0-07-881346-8, 850 pp., 7°%x 9% 
Borland-Osborne/McGraw-Hill Programming Series 


Turbo Pascal 
THE COMPLETE REFERENCE 


Covers Version 4 

by Stephen O'Brien 

The first single resource that 
TURBO lists every Turbo Pascal com- 
PASCAL mand, function, and feature, 

all illustrated in short examples 
and applications. Ideal for 

every Turbo Pascal programmer. 


$24.95 Paperback, ISBN: 0-07-881290-9, 814 pp., 7% x 91/4 
Borland-Osborne/McGraw-Hill Programming Series 


Turbo Pascal 4: THE POCKET REFERENCE 


by Kris Jamsa 
This little booklet puts all essential Turbo Pascal Version 4 
features and commands at your fingertips. 


$5.95 Paperback, ISBN: 0-07-881379-4, 120 pp.. 4x7 
Borland-Osborne/McGraw-Hill Programming Series 


, - TURBO PASCAL 
TURBO F “ Al Programmers 
Version 


Library 
Version 4 


Using Turbo Pascal” VERSION 4 


by Steve Wood 

Build the skills you need to become a productive Turbo 
Pascal 4 programmer. Covers beginning concepts to full- 
scale applications. 


$19.95 Paperback, ISBN: 0-07-881356-5, 546 pp., 7% x 9% 
Borland-Osborne/McGraw-Hill Programming Series 


Advanced Turbo Pascal" VERSION 4 


by Herbert Schildt 

The power of Turbo Pascal 4 will be at your fingertips when 
you learn the top-performance techniques from expert 
Herb Schildt. 


$21.95 Paperback, ISBN: 0-07-881355-7, 416 pp., 7% x 9 
Borland-Osborne/McGraw-Hill Programming Series 


Turbo Pascal* 
PROGRAMMER’S LIBRARY, SECOND EDITION 


by Kris Jamsa and Steven Nameroff 

Take full advantage of Turbo Pascal,and the newest versions 
of Turbo Pascal, with this outstanding collection of pro- 
gramming routines. Includes routines for the Turbo Pascal 
toolboxes. 


$22.95 Paperback, ISBN: 0-07-881368-9, 600 pp., 79x 9% 
Borland-Osborne/McGraw-Hill Programming Series 


by Frederick E. Mosher 

and David |. Schneider 
Introduces Turbo Basic to nov- 
ices and seasoned pros alike 
Learn about the Turbo Basic 
operating environment and the 
interactive editor 


$19.95 Paperback, 

ISBN: 0-07-881282-8, 

457 pp., 7/8 x 9% 
Boriand-Osborne/McGraw-Hill Programming Series 


Turbo C° PROGRAMMER’S LIBRARY 


by Kris Jamsa 

This powerful collection of Turbo C programming routines 
enhances the producivity and efficiency of all Turbo C 
programmers. 


$22.95 Paperback, ISBN: 0-07-881394-8, 650 pp., 7% x 9% 
Borland-Osborne/McGraw-Hill Programming Series 


ORDER TODAY! Call Us Toll-Free 800-227-0900 We accept visa, MasterCard, and American Express. 


In Canada, contact McGraw-Hill Ryerson, Ltd. Phone 416-293-1911. 


ur OsborneMcGraw-tlill 
ta) ys 2600 Tenth Street 
Bf ® Berkeley, California 94710 


Turbo Basic, Turbo C, and Turbo Pascal are registered trademarks 
of Borland International. Copyright © 1988 McGraw-Hill, Inc 


Philippe Kahn, Chairman & CEO, Borland International 
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